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PREFACE 


This manual provides the new programmer with the information he needs to run 
programs on the IBM System/3 Model 10 Disk System and to use the system utility 
programs for doing jobs such as preparing disks for use or updating system libraries. 
This information is divided into two parts: 

• Part I - operation control language (OCL) statements needed to run programs in 
the Disk System. 

• Part II - system utility programs and utility control statements needed to run them. 
Programming support for the 5445 Disk, 3410/3411 Magnetic Tape Subsystem, 
Overlay Linkage Editor and Checkpoint/Restart features is not included on the 
distribution disk cartridge unless ordered by the user. 

Note: In this publication there are some references to support of 64K bytes of main 
storage. A System/3 Model 10 with a 64K processing unit is available only as an 
RPQ. Your IBM Marketing Representative can provide information about this. 


Related Publications 

Publications that are related (not prerequisites) to this one are: 

• IBM System/3 Disk System Introduction, GC21 -7510 

• IBM System/3 Disk System RPG II Reference Manual, SC21 -7504 

• IBM System/3 Model 10 Disk System Operator's Guide, GC21 -7508 

• IBM System/3 Disk System Halt Guide, GC21-7540 

• IBM System/3 Disk System RPG If and System Additional Topics 
Programmer's Guide, GC21-7511 

• IBM System/3 Disk Concepts and Planning Guide, GC21 -7571 

• IBM System/3 Subset American National Standard COBOL Compiler and Library 
Programmer's Guide, SC28-6459 

• IBM System/3 Disk FORTRAN IV Reference Manual, SC28-6874 
Seventh Edition (September 1973) 

This is a major revision of and obsoletes GC21-7512-5, and Technical Newsletter GN21-7676. 
A new disk utility ($DCOPY) has been added. It allows the user to copy or dump the entire 
contents of a disk onto tape or tape onto disk. (This program is distributed with the magnetic 
tape feature of the SCP). 

All references to consecutive organized disk files have been changed to sequential. The FILE 
AND VOLUME LABEL DISPLAY PROGRAM ($LABEL) prints an S for sequential disk files, 
when displaying VTOC. Other minor changes are indicated by a vertical line at the left of 
the change. 

This edition applies to version 09, modification level 00 of the IBM System/3 Model 10 Disk 
System and to all subsequent versions and modifications until otherwise indicated in new 
editions or Technical Newsletters. Changes are continually made to the specifications herein; 
before using this publication in connection with the operation of IBM Systems, consult the 
latest IBM System/3 Newsletter, Order Number GN20-2228 for the editions that are applicable 
and current. 

Requests for copies of IBM publications should be made to your IBM representative or to the 
IBM branch office serving your locality. 

A form for reader's comments is provided at the back of this piblication. If the form has been 
removed, comments may be addressed to IBM Corporation, Publications, Department 245, 
Rochester, Minnesota 55901. 


©Copyright International Business Machines Corporation 1969, 1970,1971,1972,1973 
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HOW TO USE THIS MANUAL 



This publication contains two parts. Part I describes operation control language 
(OCL) statements. Part II describes system utility programs. 

Parti 

Refer to Part I if you want to know: 

1. What an OCL statement is. 

2. What each OCL statement is used for (function). 

3. Where each OCL statement is placed in relation to others and when it is needed 
(placement). 

4. How each statement must be coded (format). 

5. What each statement must contain (contents). 

Part II 

Refer to Part II if you want to know: 

1. What system utility programs are supplied with the system. 

2. The function of each utility program. 

3. The operation control language (OCL) statements and utility control statements 
necessary to request each utility program. 
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INTRODUCTION TO OCL STATEMENTS 


WHAT IS OCL? 

Operation control language (OCL) is your means of communicating with the IBM 
System/3 Model 10 Disk System. You must write a set of OCL statements for each 
program you want to run. Based on the information supplied by the OCL state¬ 
ments, the Disk System will load and execute your Disk System programs or 
perform system utility functions. 

You can supply OCL statements in two ways: (1) punch the statements into 
cards, which are then read by the Disk System; (2) use the printer-keyboard to 
key the statements directly to the Disk System. 

After the Disk System reads a set of OCL statements for a program, it runs the 
program. When the program ends, the Disk System reads the set of statements 
for the next program, then runs that program. This procedure is repeated until 
all OCL statements have been read and the corresponding programs have been run. 

The running of your programs is controlled by system control programs. System con¬ 
trol programs must be in core storage before your jobs can be run. These programs 
are located on disk and are brought into storage by a procedure called initial program 
load (IPL). IPL is performed by the operator when the system is turned on. For more 
information on IPL, see the IBM System/3 Disk System Operator's Guide , GC21-7508. 

The DATE statement is part of the IPL process and must be the first statement pro¬ 
vided for your program. (See DA TE Statement in Statement Descriptions for more 
information.) 
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OCL and the Job Stream 

The OCL statements you supply form the basis of the job stream . If your program 
requires the use of data from the system input device (the device used to read OCL 
statements) your program and that data must follow the corresponding OCL. The job 
stream, therefore, can contain programs and program data as well as OCL statements. 
Figure 1 is an example of a card input job stream. 

You can also store sets of OCL statements for your programs outside of the job stream 
in a source library on disk. These sets are called procedures . You can instruct the 
system to merge procedures into the job stream. The ability to store sets of frequent¬ 
ly used OCL statements on disk makes it possible to avoid recoding the statements 
every time they are used. (See Procedures under Statement Descriptions for more in¬ 
formation.) 

ORGANIZATION OF PART I 

Part I is divided into: 

1. Coding Ruies defines the general contents of the OCL statements and explains the 
rules for writing the statements. 

2. Statement Descriptions explains the functions, format, and contents of each OCL 
statement, and the places in the job stream the statement may be used. 

3. Statement Examples presents and explains a job stream containing most of the OCL 
statements. 



Figure 1. Job Stream 


















































CODING RULES 


TYPES OF INFORMATION 

Operation control language (OCL) statements contain, at most, two types of inform¬ 
ation: a statement identifier and parameters. A statement identifier is information 
that tells one statement from another. A parameter is additional information supplied 
with the statement identifier. Figure 2 shows the general form of OCL statements. 


Identifier Parameter 1, Parameter 2, Parameter n 


Figure 2. General Form of OCL Statements 


Statement Identifiers 

Every OCL statement needs a statement identifier. The identifiers are as follows: 


DATE 

LOAD 

RUN 

SWITCH 

COMPILE 


IMAGE 

FORMS 

LOG 

READER 

PUNCH 


NOHALT 
HALT 
* (asterisk) 
PAUSE 
/& 


FILE 

BSCA 

CALL 

PARTITION 

LOCKOUT 


LOAD is an example of a statement identifier. 



Parameters 

Some statements need parameters. Others do not. (See Statement Descriptions for 
an explanation of the statements which need parameters.) Parameters can be 
either codes or data. A code is a word or group of characters that has a certain 
meaning. Data is information such as the names, locations, and lengths of files on 
disk. (See Statement Descriptions for data and code restrictions on parameters.) 

In the following example, PROG2 is the name of an RPG II object program, and FI 
is a code that stands for the fixed disk on drive one. PROG2 is a data parameter 
and FI is a code parameter. 
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Some statements require certain words in parameters to tell one parameter from 
another. The words are called keywords. Parameters containing keywords are 
called keyword parameters. In Figure 3, NAME-MASTER, PACK-VOL1, and 
UNIT-R1 are keyword parameters. NAME, PACK, and UNIT are keywords. 
MASTER and VOL1 are data parameters. R1 is a code parameter. There should 
always be a hyphen between the keyword and the code or data parameter. 




Figure 3. Keyword Parameters 


GENERAL CODING RULES 

In Part 1 of this book, the numbers that appear above statement formats and 
examples indicate the card columns or line positions occupied by the statements. 

In statement formats, special characters, such as //, and words written in capital 
letters are information that must be used exactly as shown. Words written in 
small letters, such as code, program-name, and unit, represent information that 
you must supply. 

Statements Beginning with // 

The rules for coding the statements are as follows (the term position refers to 
either card column or line position): 

• Place the // in positions 1 and 2. 

• Leave one or more blanks between the // and the word that forms the statement 
identifier (LOAD, RUN, CALL, etc.). 

• Leave one or more blanks between the end of the statement identifier and the 
first parameter. 

• If you need more than one parameter, use a comma to separate them. No blanks 
are allowed within or between parameters. (For the exception to this rule, see the 
description for the HI KEY parameter under Multivolume Files.) Anything 
following the first blank is considered a comment (see Comments). 

• If you are writing keyword parameters, place the keyword first and use a 
hyphen to separate the keyword from the code or data parameter. 

• If the parameter is not a keyword parameter, write the parameters in the order 
in which they are discussed in this manual. 



Figure 4 illustrates the coding rules. The statement identifiers are LOAD and 
FILE. The parameters are PROG1, R1, NAME-MASTER, UNIT-R1, and PACK- 
VOL1. The last three parameters are keyword parameters. 
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Figure 4. Illustration of General Coding Rules 


Statements Beginning with Other Than // 

• and /& statements do not require // preceding them when coded. (See Statement 
Descriptions for * and /& statements.) 

Continuation 

All OCL statements except FILE must not exceed 96 characters, including blanks 
and comments. Because of the large number of parameters possible in a FILE 
statement, you can use two or more cards or lines for those statements. Each card 
or line you use must not exceed 96 characters. (Data for the IMAGE statement 
requires continuation for the cards or lines containing the chain image characters, 
but the data follows different continuation rules. See IMAGE Statement under 
Statement Descriptions for more information.) 

The continuation rules are as follows: 

• Place a comma after the last parameter in every card or line except the last. 

The comma, followed by a blank, tells the system that the statement is con¬ 
tinued in the next card or line. 

• Begin each new card or line with a // in positions 1 and 2. 

• Leave one or more blanks between the // and the first parameter in the card or 
line. (See HIKEY Parameter under Multivolume Files for exception to this rule.) 

Figure 5 illustrates the continuation rules. 
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Figure 5. Illustration of Continuation Rules 




Comments 

You can include comments in the following places in your statements: 

• Following the // in statements beginning with //. Begin the comment in position 3, 
immediately following the //. You can use up to eight characters without blanks. 
Leave one or more blanks between the comment and the word forming the state¬ 
ment identifier. Figure 6 contains such a comment. The word BILLING is the 
comment. 

• After the last parameter. Leave one or more blanks between the last parameter 
and your comment. The comment can be any combination of characters. If the 
statement is continued in subsequent cards or lines, you can place comments after 
the last parameter in any of the cards or lines. 


• After statements without parameters. Leave one or more blanks between the 
statement identifier and your comment. Examples of statements without 
parameters are: /&, // PAUSE, and // RUN. 


In addition to writing comments within your OCL statements, you can include whole 
cards or lines of comments. The OCL comment statement is provided for that 
purpose. (See * (Comment) Statements under Statement Descriptions for more 
information.) 


1 4 8 12 16 20 24 28 32 36 40 44 



Figure 6. Comment Following // 




STATEMENT DESCRIPTIONS 


Each OCL statement is described separately in this section. The following informa¬ 
tion is given for each statement: 

1. The function of the statement. 

2. The placement of the statement in regard to other statements and the circum¬ 
stances under which the statement is needed. 

3. The format of the statement. 

4. The contents of the statement, explaining the parameters that can be used in the 
statement. 

Figure 7 gives the function, placement, and restrictions on use for each OCL 
statement. 

Figure 8 describes the contents of the OCL statements. It is meant for reference 
only. If you are not familiar with an entry, or you do not know when to use or 
omit it, refer to the proper statement in the remainder of this section. 

When using Figure 8, remember that words written in small letters such as filename 
or value require a choice on your part, depending on the functions you want the 
statement to perform. Refer to Figure 8 to see which parameters are available. 
Those parameters that are capitalized must be coded along with the data or code 
parameter. 
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STATEMENT 

FUNCTION 

PLACEMENT 

RESTRICTIONS ON USE 

STATEMENT APPEARS 

IN JOB STREAM 

STATEMENT APPEARS 

IN A PROCEDURE 

// DATE 

Supplies the system with 
a date, this date is given 
to disk files being created. 

Must follow LOAD or CALL 
statement and precede the 
RUN statement except at 

IPL time, when it must 
precede the first LOAD 
or CALL statement. 

Must follow the LOAD 
statement and precede the 
RUN statement (if RUN is 
used). 

Must be supplied during the 
Initial Program Load. The 
effect of the statement is 
for that job only. 

// LOAD * 

Indicates that the object 
program will be loaded 
from the system input 
device following the 

RUN statement. 

Must precede the 

RUN statement 

Must be the first 

// statement. 

LOAD * cannot be used in 
program level 2. 

// LOAD 

Identifies the program 
to be run and in¬ 
dicates the disk that 
contains the object 
library from which it is 
to be loaded. 

Must precede the 

RUN statement. 

Must be the first 
// statement. 

. . . . - .. . . . . 


II RUN 

Indicates the end of the 
OCL statements for a 
program and tells system 
to run the program. 

Must be the last OCL 

statement. 

May be the last 
statement. 

Required in the job stream 
for each program which is 
to be run. 

// SWITCH 

Used to set one or more 

external indicators on 

or off or leave the in¬ 
dicator as it is. 

Must follow LOAD or CALL 
statement and precede the 
RUN statement. 

Must follow the LOAD 
statement and precede the 
RUN statement (if RUN is 
used). 


// COMPILE 

Tells the system where 
the source program to 
be compiled is located 
and where to place the 
object program. 

Must follow LOAD or CALL 
statement and precede the 
RUN statement. 

Must follow the LOAD 
statement and precede the 
RUN statement (if RUN is 
used). 


// IMAGE 

Tells the system to re¬ 
place the chain-image 
area with characters 
indicated in the fol¬ 
lowing data cards or 
characters keyed in 
! or read from source 
j library. 

Anywhere among the 

OCL statements. 

Must precede the 

PUN statement (if 

RUN is used). 

Required if the printer chain 
has been changed. 

// FORMS 

Instructs the system to 
change the number of 
lines printed per page. 

Anywhere among the 

OCL statements. 

Must precede the 

RUN statement (if 

RUN is used). 


// LOG 

Instructs system to 
start or stop printing 

OCL statements and 
i codes and indicates the 
device to be used to 
print them. 

Anywhere among the 

OCL statements. 

Must precede the RUN 
statement (if RUN is 
used). 

Device cannot be 
specified in program 
level 2. 

// READER 

Changes the system input 
device used to read OCL 

statements. 

Must precede LOAD or 
CALL statement or follow 
the RUN statement and 
precede the next LOAD 
or CALL statement 

Must precede the 

LOAD statement (if 

LOAD is used). 

In a procedure, the input 
device is not changed until 
the procedure is completely 
executed. 


Figure 7 (Part 1 of 2). Table of OCL Statements 
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STATEMENT 

FUNCTION 

PLACEMENT 

RESTRICTIONS ON USE 

STATEMENT APPEARS 

IN JOB STREAM 

STATEMENT APPEARS 

IN A PROCEDURE 

// PUNCH 

Enables you to change 
the system punch device. 

Anywhere among the 

OCL statements. 

Must precede the RUN 

statement. 


// NOHALT 

Instructs system to 
continue without 
stopping when a 
program ends. 

Anywhere among the 

OCL statements. 

Must precede the RUN 
statement (if RUN is 
used). 

Ignored in program level 2. 

// HALT 

Instructs system to halt 
when program ends; 
cancels the effect of 

the NOHALT 

statement. 

Anywhere among the 

OCL statements. 

Must precede the RUN 
statement (if RUN is 
used). 

Ignored in program level 2. 

^(Comment) 

Used to explain the job 
or give the operator 
instructions; does not 
affect the program in 
operation. 

Anywhere. 

Anywhere. 


// PAUSE 

Tells the program to stop 
in order to give the 
operator time to per¬ 
form a function. 

Operator must restart 
program. 

Anywhere among the 

OCL statements. 

Must precede the 

RUN statement (if 

RUN is used). 


/& 

Provides OCL security 
from previous job. 

Recommended as the first 
statement of a job. 

Not allowed in a 
procedure. 

Can be used in the job stream 
only. ! 

//FILE 

Supplies information 
about the file to the 

system. 

Must follow LOAD or CALL 
statement and precede the 
RUN statement. 

Must follow the LOAD 
statement and precede the 
RUN statement (if RUN 
is used). 

Required for every new file 
created and existing files being 
used. 

// BSCA 

Changes the BSCA line 
number. 

Must follow LOAD or 

CALL statement and 
precede the RUN state¬ 
ment. 

Must follow the LOAD 
statement and precede 
the RUN statement (if 

RUN is used). 


// CALL 

Identifies procedure to 
be merged into job 
stream and the disk 
containing the source 
library from which to 
read the procedure. 

Must precede the 

RUN statement. 

Indicates chained 
procedures. 

Can be no more than nine 
levels of nested chained 
procedures. 

// PARTITION 

Guarantees a minimum 
size to level 2 for a 
program in that level. 

Anywhere, among the 

OCL statements. 

Must precede the RUN 
statement (if RUN is 
used). 

Cannot be submitted in 
program level 2 or when 
program level 2 is processing. 

// LOCKOUT 

Disables the other pro¬ 
gram level to allow 
fast job initiation in 
the program level in 
which the LOCKOUT 

card was read. 

Anywhere among the 

OCL statements. 

Must precede the RUN 
statement (if RUN is used). 

Ignored on a non-DPF system. 


Figure 7 (Part 2 of 2). Table of OCL Statements 
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STATEMENT 

PARAMETER 

CODE 

MEANING OF CODE 

// DATE 

date 

mmddyy or 
ddmmyy 

System date or date within a set of statements 

// LOAD 

asterisk 

* 

Program is to be loaded from the system input device 


program name 

name 

Name of program that is to be loaded from disk 


unit 

R1 

Object library resides upon: 

Removable disk on drive one 



R2 

Removable disk on drive two 



FI 

Fixed disk on drive one 



F2 

Fixed disk on drive two 

// RUN 

none 



// SWITCH 

indicator-settings 

Refer to SWITCH 
Statement under 
Statement Descriptions 


// COMPILE 

SOURCE 

SOURCE-name 

Name of source program 


UNIT 

UNIT-R1 

Where disk that contains the source library is 



R2 

located (the meanings of the unit codes are the 



FI 

same as for LOAD) 



F2 



OBJECT 

OBJECT-R1 

Where to place the object program (the meanings 



R2 

of the unit codes are the same as for LOAD) 



FI 




F2 


// IMAGE 

format 

| HEX 

To indicate characters from cards are in hexadecimal 
form 



CHAR 

To indicate characters from cards are in EBCDIC form 



MEM 

To indicate characters are from the source library 


number 

value 

Number of new characters 


name 

name 

Identifies the characters in the library 


unit 

R1 

Where the disk that contains the library is located 



R2 

(the meanings of the unit codes are the same as for 



FI 

LOAD) 



F2 


// FORMS 

DEVICE 

DEVICE-name 

Indicates which printer is used 


LINES 

LINES-value 

Indicates number of lines to be printed per page 

// LOG 

code 

CONSOLE 

Use printer-keyboard as logging device 



PRINTER 

Use printer as logging device 



OFF 

Stop printing 



ON 

Start printing 

// READER 

system input device 

CONSOLE 

Printer-keyboard 



MFCU2 

Secondary hopper of MFCU 



MFCU1 

Primary hopper of MFCU 

: 


1442 

Card Read/Punch 

// PUNCH 

system punch device 

MFCU2 

Secondary hopper of MFCU 

! 


MFCU1 

Primary hopper of MFCU 

i 


1442 

Card Read/Punch 


Figure 8 (Part 1 of 4). Table of Parameters 
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STATEMENT 

PARAMETER 

CODE 

MEANING OF CODE 

// NOHALT 

none 



// HALT 

none 



* (Comment) 

none 



// PAUSE 

none 



/& 

none 



// FILE 
' (Disk 

Files) 

NAME 

UNIT 

NAME-filename 

UNIT-R1 

R2 

FI 

F2 

Name the program uses to refer to the file 

Where the 5444 disk that contains or will contain the 
file is located (the meanings of the unit codes are the 
same as for LOAD) 



D1 

D2 

Where the 5445 disk that contains or will contain 
the file is located. 


PACK 

PACK-name 

Name of disk that contains or will contain the file 


LABEL 

LABEL-filename 

Name by which your file is identified on disk 


RECORDS or 

TRACKS 

RECORDS-number of 

TRACKS-number 

Amount of space needed on a disk for a file 


LOCATION 

LOCATION-track 

number 

Number of track on which file begins or is to begin 
(5444 disk only) 



LOCATION-cylinder 
number 

Cylinder number on which file begins or is to begin. 
Track assumed zero (5445 disk only). 



LOCATION-cylinder 
number/track number 

Cylinder number, track number on which file begins 
or is to begin (5445 disk only). 



LOCATION-filename 

Filename of a split cylinder file that is the first split 
cylinder file in a group, or is an already existing split 
cylinder file. (5445 disk only). For further discus¬ 
sion see Split Cylinder Files. 


RETAIN 

RETAIN-T 

S 

P 

A 

Temporary file 

Scratch file 

Permanent file 

Reactivate scratch file 


DATE 

DATE-mmddyy 

ddmmyy 

Tells the system the date the file was created 


HIKEY 

HI KEY-'highest 
key fields allowed' 

List of highest key fields 
allowed on each pack 


SPLIT 

SP L1T-tracks/cy 1 i nders 

or 

SPLIT-tracks 

The number of tracks per cylinder needed for the 
split cylinder file; the number of cylinders needed 
for a group of split cylinder files (5445 disk only). 

For further discussion see Split Cylinder Files. 


Figure 8 (Part 2 of 4). Table of Parameters 
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STATEMENT 

PARAMETER 

CODE 

MEANING OF CODE 

// FILE 

NAME 

NAME-filename 

Name the program uses to refer to the file. 

(Tape File) 

' 

UNIT 

UNIT-T1 

T2 

T3 

T4 

Where the tape that contains or will contain the 
file is mounted. 


REEL 

REEL-name 

Name of the tape that contains or will contain the 
file. 



-NL 

The tape is not labeled. 



-NS 

The tape contains non-standard labels. 


LABEL 

LABEL-filename 

or 

LABEL-'character 

string' 

Name by which your file is identified on tape. 


DATE 

DATE-mmddyy 

ddmmyy 

Tells the system the date the file was created. 


RETAIN 

RETAIN-nnn 

The number of days a file should be retained before 
it expires. 


BLKL 

BLKL-block length 

The number of bytes in a physical block of tape. 


RECL 

RECL-record length 

The number of bytes in a logical record. 


RECFM 

RECFM-F 

Fixed length, unblocked records. 



-V 

Variable length, unblocked records. 



-D 

Variable length, unblocked, D-type ASCII records. 



-FB 

Fixed length, blocked records. 



-VB 

Variable length, blocked records. 



-DB 

Variable length, blocked, D-type ASCII records. 


END 

END-LEAVE 

The tape remains in its present position after the 
file is processed. 



-UNLOAD 

The tape is rewound and unloaded after processing. 



-REWIND 

The tape is rewound after processing. 


DENSITY 

DENSITY-200 

The tape will be written at 200 bpi (bits per inch) 
density. 



-556 

The tape will be written at 556 bpi density. 



-800 

The tape will be written at 800 bpi density. 



-1600 

The tape will be written at 1600 bpi density. 


Figure 8 (Part 3 of 4). Table of Parameters 
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STATEMENT 

PARAMETER 

CODE 

MEANING OF CODE 


ASCII 

ASCII-YES 

An ASCII file is being processed. 



-NO 

An EBCDIC file is being processed. 


DEFER 

DEFER-YES 

The tape volume will be mounted later. 



-NO 

The tape is presently mounted. 


CONVERT 

CONVERT-ON 

Data read from or written to a seven track tape file 
will be converted. 



-OFF 

Data read from or written to a seven track tape file 
will not be converted. 


TRANSLATE 

TRANSLATE-ON 

Data read from or written to a seven track tape file 
will be translated. 



-OFF 

Data read from or written to a seven track tape file 
will not be translated. 


PARITY 

PARITY-EVEN 

The seven track tape file will be read or written in 
even parity. 



-ODD 

The seven track tape file will be read or written in 
odd parity. 

// BSCA 

LINE 

LINE-1 

Change all BSCA DTF line codes to the line number 



2 

specified. 

„ . ... 

// CALL 

procedure name 

name 

Name that identifies the procedure in the source 
library 


unit 

R1 

Where the disk containing the procedure is located 


I 

R2 

(the meanings of the unit codes are the same as for 



FI 

LOAD) 



F2 


// PARTITION 

size 

value 

Minimum size of program level 2 in decimal bytes 

// LOCKOUT 

none 




Figure 8 (Part 4 of 4). Table of Parameters 
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DATE STATEMENT 


Function 


Placement 


Format 

Contents 


Example 


The DATE statement gives the Disk System a date, called the system date. The 
system date is referred to by RPG II field names UDATE, UMONTH, UDAY, 
and UYEAR. The preceding field names can also be used when referring to the 
date given to the disk files when they were created. 

A DATE statement within the set of statements for a program changes the 
system date, but only for that program. When the program ends, the date 
supplied in the DATE statement at IPL time is again used. There can only be 
one DATE statement per job. 

A DATE statement is always required during Initial Program Load (IPL). It is 
the only OCL statement required by the system at that time. 

A DATE statement can also appear within any of the sets of statements for your 
programs. The DATE statement must follow the LOAD or CALL statement 
and precede the RUN statement. 

// DATE date 

The system date can be in either of two forms: month-day-year (mmddyy) or 
day-month-year (ddmmyy). You must specify the form at System Generation 
time. (See IBM System/3 Disk System Operator's Guide, GC2I-7508, for more 
information on System Generation.) The date you specify must be in that form. 

The date can be written with or without punctuation. For example, July 25,1970, 
could be specified in any one of the following ways: 

07-25-70 

25-07-70 

072570 

250770 

Month, day, and year must each be 2-digit numbers but lead zeros in month and 
day may be omitted when punctuation is used (7-25-70 or 25-7-70). In the 
punctuated form, any characters except commas, quotes, numbers and blanks 
can be used as punctuation. 
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LOAD STATEMENT 


Function The LOAD statement identifies the program to be run and indicates whether the 

program will be loaded from the system input device or disk. 

Placement One LOAD statement is required within each of the sets of statements for your 

programs. If the set of statements appears on the job stream, the only requirement 
for the LOAD statement is that it must precede the RUN statement. In procedures, 
the LOAD statement must precede the RUN statement. (For more information about 
procedures, see Procedures in this section ) 

Format The LOAD statement has two formats. The first format is used for object pro¬ 

grams loaded from the system input device and cannot be used in a procedure. 

The second format is used for programs loaded from disk. 

// LOAD * 

// LOAD program-name,unit 

Contents Asterisk: An asterisk indicates that the object program will be loaded from the 

system input device. Program-name and unit parameters must not be included. 

The cards or lines that contain the program must follow the RUN statement for 
the program and must be followed by /* or /& to signify the end of the program. 
LOAD* cannot be used in programming level 2 or in procedures (see Using OCL, 
Loading Programs in a DPF Environment , for more information on dual programming). 

Program-name: The program-name parameter is the name used on disk to identify 
the program. Commas, apostrophes, periods, and blanks may not be used in the 
program name. 

The names you must use for your programs depend on the way the programs were 
placed on disk. One way includes a compiler option. You can specify that your 
program be placed on disk immediately after it is compiled. The name you supply 
to the compiler is the name used to identify the program. 

Another way to place your program on disk is by using the Library Maintenance 
program. If you used that program, the program-name you supplied in the Library 
Maintenance control statements is the name used to identify your program. (For 
more information, see Library Maintenance in Part II of this book.) 
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LOAD STATEMENT (continued) 


The Disk System programs are identified by the following names: 


Program 

Name 

Alternate Track Assignment 

SALT 

Alternate Track Rebuild 

SBUILD 

Assembler 

SASSEM 

COBOL 

SCBLOO 

Data Recording 

SDREC 

Data Verifying 

SDVER 

Disk Copy/Dump 

SCOPY 

Disk Initialization 

$1 NIT 

Disk Sort 

SDSORT 

Dump Restore 

SDCOPY 

File and Volume Label Display 

SLABEL 

File Delete 

SDELET 

FORTRAN 

SFORT 

Library Maintenance 

SMAINT 

List 

SCLIST 

Macro Processor 

SMPXDV 

MFCU Sort/Collate 

SCSORT 

Overlay Linkage Editor 

SOLINK 

Reproduce and Interpret 

SREPRO 

Remote Job Entry 

SSRJE 

Restart 

SSRSTR 

RPG II Auto-Report 

SAUTO 

RPG II Compiler 

SRPG 

Tape Initialization 

STINIT 
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LOAD STATEMENT (continued) 


Tape Sort 

$TSORT 

Tape Error Summary Program 

$TVES 

5445 Data Interchange 

$VTOC 

1255 Utility 

$MICR 

1270/1255 Utility* 

$MOCR 

80-96 Conversion 

$CNVRT 

*Not valid within the United States. 


Unit: The unit parameter is a code. It indicates where the disk that contains 
the program is located. The codes are as follows: 

Code 

Meaning 

R1 

Removable disk on drive one 

FI 

Fixed disk on drive one 

R2 

Removable disk on drive two 

F2 

Fixed disk on drive two 


The unit parameter is required because your programs can be on any of the 
disks on your disk unit. The disk area containing your object program is called 
an object library. You can create an object library on any of the disks on your 
disk unit by using the Library Maintenance program. (See Library Maintenance 
in Part II of this manual.) 

Example In the following sample LOAD statement, $RPG is the name that identifies the 

RPG 11 Compiler. 


|l 4 8 12 16 20 24 28 32 36 40 44 48 


mmmmmi 

m 


in 

in 

hi 

in 

in 

in 

in 

m 

llll 

immiiiiiiii 

hi 


in 

in 

in 

in 

hi 

in 

in 

hi 

llll 


FI is the code indicating the fixed disk on drive one, where the compiler would 
be located in this case. 
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RUN STATEMENT 


Function 


Placement 


Format 


The RUN statement indicates the end of the OCL statements for a program. 

After the system reads the RUN statement, it runs the program. 

A RUN statement is needed for each of the programs you want the system to run. 
In the job stream, it must be the last statement within each of the sets of OCL 
statements for your programs. It can also be the last OCL statement in a pro¬ 
cedure. (For more information about procedures, see Procedures in this section.) 

//RUN 


Contents 


None. (Comments may be entered starting in column 8.) 
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SWITCH STATEMENT 


Function 


Placement 


Format 

Contents 


Example 


The purpose of the SWITCH statement is to set one or more RPG II external 
indicators on or off. The indicators are always off after the operator uses the 
IPL procedure to start the system. If a SWITCH statement is used to set an 
indicator on, the indicator remains on until another SWITCH statement sets it 
off, or until the operator again uses the IPL procedure to start the system. There 
can be only one SWITCH statement per job. 

The SWITCH statement can appear within any of the sets of statements for your 
programs. The only requirements for the SWITCH statement are that it must 
follow the LOAD or CALL statement and precede the RUN statement. 

//SWITCH indicator-settings 

Indicator-settings: The indicator-settings parameter is a code that consists of 
eight characters, one for each of the eight external indicators (U1-U8). The first, 
or leftmost, character gives the setting of indicator U1; the second character 
gives the setting of U2; and so on. 

The code must always contain eight characters. For each indicator, one of the 
following characters must be used: 

Character Meaning 

0 Set the indicator off 

1 Set the indicator on 

X Leave the indicator as it is 

The code 1X0110XX would cause the following results: 


Indicator 

Result 

U1 

Set on 

U2 

Unaffected 

U3 

Set off 

U4 

Set on 

U5 

Set on 

U6 

Set off 

U7 

Unaffected 

U8 

Unaffected 
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COMPILE STATEMENT 


Function The COMF1 LE statement tells the system two things: (1) where the source pro¬ 

gram to be compiled is located if it is coming from a disk source library; (2) where 
the object program is to be placed. (An object program is a source program which 
has been compiled or translated into machine language.) 

Placement The COMPI LE statement must be within the set of OCL statements that apply 

to the compilation. The COMPILE statement must follow the LOAD or CALL 
statement and precede the RUN statement. 

Format // COMPI LE parameters 

Contents All the parameters are keyword parameters (keywords are in capital letters). The 

keywords are: SOURCE, UNIT, and OBJECT. 


SOURCE: The SOURCE parameter tells the system the name of the source pro¬ 
gram. The keyword SOURCE must be followed by the name of the source pro¬ 
gram on disk. The name is the name by which the source program is identified 
on disk in the source library. (For more information concerning the source library 
see CALL Statement in this section.) 

The only way you can place source programs in a source library is by using the 
Library Maintenance program. The program name you supply in Library Main¬ 
tenance control statements is the name used to identify the source program in 
the library. (For more information, see Library Maintenance in Part II of this 
manual.) 

If the SOURCE parameter is not used, the source program is assumed to be in the 
job stream following the RUN statement. 

The SOURCE parameter must always be accompanied by the UNIT parameter. 


UNIT: The UNIT parameter is used only when the SOURCE parameter is used. 

The UNIT parameter is a code indicating where the disk that contains the source 
library is located. The codes are as follows: 


Code 

Meaning 

R1 

Removable disk on drive one 

FI 

Fixed disk on drive one 

R2 

Removable disk on drive two 

F2 

Fixed disk on drive two 
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COMPILE STATEMENT (continued) 


OBJECT: The OBJECT parameter tells the system where to place the object pro¬ 
gram. The OBJECT parameter may be specified without using the SOURCE and 
UNIT parameters. The codes which are used to indicate the disk unit on which 
the object program is to be placed are R1 r F2 f R2, or F2. 

Note: If the OBJECT parameter is omitted, it is assumed that the object program 
is to be placed on the same disk as the compiler. 


Example The following sample COMPILE statement tells the system that the source program 

with the name PROG3 is located on the fixed disk on drive one (FI). 
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The parameter, OBJECT-R1, tells the system to place the object program on the 
removable disk on drive one. 
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IMAGE STATEMENT 


Function To operate correctly, the printer requires characters matching those on the 

printer chain to be in a special area of core storage called the chain-image area. 
When you replace the printer chain with one having different characters, you must 
also change the contents of the chain-image area. 

The IMAGE statement instructs the system to replace the contents of the chain- 
image area with the characters indicated by the statement. The characters can be 
entered from the system input device, or contained in a source library on disk. 

The effect of the IMAGE statement is temporary and the system chain image is 
returned to the chain-image area when IPL occurs. 

Placement The IMAGE statement can appear anywhere among the OCL statements. In a 

procedure, it must precede the RUN statement. 

Format // IMAGE parameters 

Contents The IMAGE statement tells the system either of two things: (1) the new chain 

characters are to be read from the system input device; or (2) the new chain 
characters are to be read from the source library. 

The IMAGE parameters are: 

form at -HEX, CHA R, or MEM 

— number-value 

— name-name 

— unit-code 

(Coding only HEX, CHAR, or MEM is preferable for format but HEXADECIMAL, 
CHARACTER, or MEMBER can be coded.) 


Characters From the System Input Device 

If you wish to indicate that the new chain characters are to be read from the 
system input device, use the following parameters: 


Format: Use the word CHAR to indicate that the characters are in EBCDIC form. 
Use the word HEX to indicate that the characters are in hexadecimal form. 

Number: The number parameter must be used with HEX and CHAR. It must be 
a value which is equal to the number of columns or line positions in the data cards 
or the data keyed in following the IMAGE statement that contains the new charac¬ 
ters. This number must not exceed 240 when the characters are hexadecimal, 120 
when characters are EBCDIC. The name and unit parameters must not be coded. 
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IMAGE STATEMENT (continued) 


Following are the rules for punching or keying the new characters: 

1. The characters must begin in column or line position 1. 

2. Consecutive'card columns or line positions must be used; however, only 
the first 80 columns or line positions of the card or line can be used. Hexa¬ 
decimal requires an even number of columns or line positions, two per 
character. 

3. To continue the characters on another card or line begin the characters 
in column or line position 1. 


Characters From the Source Library on Disk 

To indicate that new chain characters are to be read from the source library on 
disk, the format parameter must specify the word MEM. 

The following parameters must also be included: 


Name: The name parameter identifies the source member containing the charac¬ 
ters in the library. The only way you can place the characters in a source library 
is by using the Library Maintenance program. The name you supply in Library 
Maintenance control statements is the name used to identify the characters in 
the source library. 

Unit: The unit parameter must be used with the name parameter. It is used to 
tell the system where the disk containing the source library is located on the disk 
unit. The codes which are used are: 


Code 

Meaning 

R1 

Removable disk on drive one 

FI 

Fixed disk on drive one 

R2 

Removable disk on drive two 

F2 

Fixed disk on drive two 
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IMAGE STATEMENT (continued) 


Example The IMAGE statement in example A tells the system that the new characters are 

on data cards or keyed in. The format parameter indicates that new characters 
are in hexadecimal form; the number parameter indicates that there are 120 
columns or line positions containing the new characters. 

In example B, the new characters, on data cards or keyed in, are in EBCDIC. The 
number parameter indicates that there are 48 columns or line positions contain¬ 
ing the new characters. 

Example C tells the system that the new characters are to be read from the 
source library on disk. The format parameter indicates that the new chain 
characters are in the source library. The name parameter indicates that the 
characters were named CHAIN in the source library. The unit parameter indi¬ 
cates that the source library containing them is on the removable disk on drive 
one (R1). Examples of the member specified in example C are the data por¬ 
tions of examples A and B. The member itself requires a // IMAGE card with 
the characters either in hexadecimal or EBCDIC. The number of columns or 
line positions containing the characters must also be specified. 


{See Library Maintenance in Part II for restrictions on the name used in coding 
MEM.) 
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FORMS STATEMENT 


Function The FORMS statement enables you to change the number of lines that the print¬ 

er will print per page. The printer automatically assumes the number of lines 
per page specified at system generation time unless a FORMS statement is used 
or a user program specifies some other number. This number of lines is effective 
until another FORMS statement is used or a user program specifies another number. 


Placement The FORMS statement can be placed anywhere among the OCL statements. 

In a procedure it must precede the RUN statement. 

Format //FORMS parameters 

Contents All of the parameters are keyword parameters (keywords are in capital letters). 

The parameters are as follows: 

( 5203 

DEVICE-< 5203L 
1 5203R 

— LINES-value 

DEVICE: The keyword for this parameter is DEVICE. It must be followed by 
the name of the printing device. For an IBM 1403 Printer or a single carriage IBM 
5203 Printer, either 5203 or 5203L is a valid device name. For a dual carriage 
IBM 5203 Printer, either 5203 or 5203L specifies the left carriage and 5203R 
specifies the right carriage. You may omit the DEVICE parameter entirely. 

LINES: The LINES parameter is used to indicate the number of lines per page. 
The maximum number of lines that can be specified per page is 112. The LINES 
parameter remains in effect until either an I PL is performed or another FORMS 
statement for the same device is read. If a line counter specification is used in an 
RPG II program, it remains in effect only for the duration of the program. 

Example In the following FORMS statement, the system is using the left carriage of the 

5203 Printer. The statement tells the system that the forms length is 88 lines 
per page. 
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LOG STATEMENT 


Function OCL statements and message codes are printed on the printer-keyboard. If your 

system has no printer-keyboard, the statements and codes are printed on the 
printer. The device used to print OCL statements and message codes is called 
the logging device. If you want to change the logging device, or specify whether 
or not the statements and codes are to be printed, you must use a LOG statement. 

The LOG statement tells the system to do one of four things: 

— Use the printer as the logging device 

— Use the printer-keyboard as the logging device 

— Stop printing OCL statements and message codes 

— Start printing OCL statements and message codes 

You can use the LOG statement within any of the sets of OCL statements for 
your programs. In a procedure it must precede the RUN statement. 


// LOG code 

Four codes can be used as parameters. The codes are as follows: 


Placement 

Format 

Contents 


Code 

Meaning 

CONSOLE 

Use printer-keyboard as logging 


device 

PRINTER 

Use printer as logging device 

OFF 

Stop printing 

ON 

Start printing 


Only one code can be used in one LOG statement. The starting of the logging 
device is implied when coding CONSOLE or PRINTER. 

When the system reads a LOG statement that contains the OFF code, it stops 
printing OCL statements and message codes. The only way you can instruct the 
system to start printing them again is by using a LOG statement that contains the 
ON, PRINTER, or CONSOLE code. When ON is specified printing resumes on 
the last logging device specified. However, the system will suspend logging during 
the time that the log device (excluding the 5471) is allocated to a program in 
either program level. Logging resumes when the program using the log device 
goes to end of job. 
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READER STATEMENT 


Function The device used to read OCL statements is called the system input device. The 

system assumes that the system input device is the primary hopper of the MFCU. 
You must use a READER statement if you want to use the printer-keyboard, 
secondary hopper of the MFCU, or the 1442 Card Read/ Punch as the system 
input device. 

Placement The READER statement must not come between the LOAD or CALL statement 

and a RUN statement. The READER statement must precede the initial LOAD 
or CALL statement or follow the RUN statement, preceding the next LOAD or 
CALL statement. If you use the READER statement in a procedure, the system 
input device is not changed until the procedure is completely executed. If you 
use the READER statement to change the system input device, the device you 
specify is used to read source programs, control statements, or OCL statements. 
Changing the system input device affects the placement of source programs and 
control statements as well as OCL statements. 

You must place the READER statement in the current system input device. 


Format // READER code 

Contents The codes are: 


Code 

Meaning 

CONSOLE 

Printer-keyboard 

MFCU2 

Secondary Hopper of the 


MFCU 

MFCU1 

Primary Hopper of the MFCU 

1442 

Card Read/Punch 
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PUNCH STATEMENT 


Function 


Placement 


Format 


Contents 


The PUNCH statement enables you to change the system punch device. 

The PUNCH statement can be placed anywhere among the OCL statements. 
In a procedure it must precede thf RUN statement. 

// PUNCH code 

Three codes can be used as parameters. They are: 


Code 

Meaning 

MFCU1 

Primary Hopper of the MFCU 

MFCU2 

Secondary Hopper of the 


MFCU 

1442 

Card Read/Punch 
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NOHALT STATEMENT 


Function 


Placement 


Format 


Normally the system halts when a program ends. The NOHALT statement tells 
the system to continue by reading the next set of OCL statements without stop¬ 
ping, when a program ends. The effect of this statement lasts until the system 
reads a HALT statement or an IPL occurs. The effect of the NOHALT statement 
is ignored temporarily when an abnormal job halt occurs. The system reverts to 
the NOHALT mode after a response. 

A NOHALT statement can be placed anywhere among the OCL statements. In a 
procedure it must precede the RUN statement. The NOHALT statement is ignored 
if loaded in program level 2. 

// NOHALT 


Contents 


None (Comments may be entered starting in column 11.) 


HALT STATEMENT 


Function 


Placement 


Format 

Contents 


The HALT statement tells the system to halt when a program ends. The operator 
can restart the system when he is ready, and the system continues reading the 
next OCL statements. 

The HALT statement is needed only if you want to cancel the effect of a NOHALT 
statement. 

A HALT statement can be placed anywhere among the OCL statements. In a 
procedure it must precede the RUN statement. The HALT statement is ignored 
if loaded in program level 2. 

// HALT 

None (Comments may be entered starting in column 9.) 


"(COMMENT) STATEMENTS 


Function Comment statements are commonly used either to explain the jobs or to give the 

operator instructions. Operator instructions are usually given in connection with 
a PAUSE statement. Comment statements are printed along with the other OCL 
statements. They have no other effect on the system. 

Placement You can include, in OCL statements, special statements that contain only com¬ 

ments. Comment statements must contain an asterisk (*) in column 1. They can 
be placed anywhere among the OCL statements in either a job stream or a pro¬ 
cedure. 


Format ^comment 

Contents The comment can be any combination of words and characters. The only require¬ 

ment is that an asterisk (*) be in column 1. 
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PAUSE STATEMENT 


Function 

The PAUSE statement causes a halt. It usually is used to give the operator time 
to prepare for the next program. He might, for example, have to place removable 
disks on the disk units or insert special forms into the printer. Comment state¬ 
ments that give the operator instructions usually precede PAUSE statements. 


When the operator [$ ready, he can restart the system. The system continues 
reading the OCL statements that follow the PAUSE statement. 

Placement 

PAUSE statements can be placed anywhere among the OCL statements. In a pro¬ 
cedure it fpjlew fhs |*QAD statement and precede the RUN statement. 

Format 

// PAUSf y||||i|||IRS 

Contents 

None (Comments mpy be entered starting in column 10.) 

/& STATEMENT 

Function 

/& statements are y$ed as a precautionary measure. Placed in front of your OCL 
set, a /& statement signals the system that a new set of OCL statements is coming. 

It prevents your statements from being read as a part of the preceding set of 
statements Any attempt to read more data from that device will be block¬ 

ed. 

Placement 

/& statements ar$ not required. It is recommended, however, that you use them 
as the firsf stbtament in each of the sets of OCL statements for your programs. 

They are not ^Ubwed ip a procedure. 

Format 

/& 

Contents 

None (Comments may be entered starting in column 4.) 


/* STATEMENT 


Function /* statements are not true OCL statements, but are used to indicate the end of a 

data file read in from a card reader or console. 

Placement A /* statement $bould be the last card of an input data file or program 

deck. 

Format /* 

Contents None (Comments may be entered starting in column 4.) 
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DISK FILE STATEMENT 


Function 

Placement 

Format 

Contents 


The FILE statement supplies the system with information about disk files. The 
system uses this information to read records from and write records on disk. 

You must supply a FILE statement for each of the new disk files that your programs 
create, and for each of the existing disk files that your programs use. The FILE state¬ 
ment must follow the LOAD or CALL statement and precede the RUN statement. 

//FILE parameters 

All of the parameters are keyword parameters. The parameters are as follows 
(keywords are in capital letters): 

— NAME-filename (in program) 

UNIT-code 

— PACK-name 

— LABEL-filename (on disk) 

— RECORDS-number or TRACKS -number 

( track number (5444 disk only) 

— LOCATION- ) cylinder number ^ 

I cylinder number/track number / 5445 only 

\ filename ) 

RETAIN-code 

— DATE-date 

— HIKEY-highest allowed key fields (on pack) 

{ tracks/cylinder ) 

or > 5445 Only 

tracks ) 

The NAME, PACK, and UNIT parameters are always required. The others are re¬ 
quired only under certain conditions. 


NAME: The NAME parameter is always needed. It tells the system the name that 
your program uses to refer to the file. The NAME parameter must be placed on 
the first card or line if two or more cards or lines are used for the FILE statement. 
(See General Coding Rules for rules on continuation.) 

For some of the programs, you must use specific names for certain files. 
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DISK FILE STATEMENT (continued) 


Program 

File 

Name 

Disk Copy/Dump 

Input 

COPYIN 


Output 

COPYO 

Disk Sort 

Input 

INPUT 


Work 

WORK (OPTIONAL) 


Output 

OUTPUT 

Assembler 

Input 

SSOURCE \ 



Work 

$WORK 1 



Output 

$WORK 2 (optional) j 


COBOL 

Compiler 

Input 

Work 

Work 

SSOURCE / 

$WORK \ 

SWORKX / 

These files 
) must be on 

a 5444 

FORTRAN 

Input 

SSOURCE 1 

i disk device. 

Compiler 

Work 

SWORK ' 


RPG II 

Input 

SSOURCE ! 

1 

Compiler 

Work 

SWORK 

1255 Utility 

Output 

FI 255 

1270 Utility 

Output 

F7055 

RPG II Auto 

Input 

SSOURCE 

Report 

Work 

SWORK 

Macro Processor 

Output 

SSOURCE 

Overlay Linkage 

Input 

SSOURCE 

Editor 

Work 

SWORK 

Any program 

Work 

SINDEX44 (For 5444 file) 

using large 


or 

indexed files 


SINDEX45 (For 5445 file) 
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DISK FILE STATEMENT (continued) 


The keyword for the parameter is NAME. It must be followed by the filename 
used by the program. The name can be any combination of characters except 
commas, quotes, or blanks. The first character must be alphabetic. The number 
of characters must not exceed 8. The following example shows how the NAME 
parameter for a file named FI LEA would be coded. 


|i 4 8 44 48 



UNIT: The UNIT parameter is always needed. It tells the system the disk that 
contains or will contain the file. The keyword for this parameter is UNIT. It 
must be followed by a code that indicates the unit. The codes are as follows: 

R1 Removable disk on 5444 drive one 

FI Fixed disk on 5444 drive one 

R2 Removable disk on 5444 drive two 

F2 Fixed disk on 5444 drive two 

D1 Removable disk on 5445 drive one 

D2 Removable disk on 5445 drive two 

The previous example shows how the UNIT parameter for a file located on the 
removable disk on 5444 drive one would be coded. 
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DISK FILE STATEMENT (continued) 


PACK: The PACK parameter is always needed for disk files. It tells the system 
the name of the disk that contains or will contain the file. The system checks this 
name to ensure that the proper disk is being used. (For information about how a 
disk is given a name, see Disk Initialization in Part II of this manual). 

The keyword for this parameter is PACK. It must be followed by the name of the 
disk. The example under NAME shows how the PACK parameter for a file on a 
disk named VO LI would be coded. 

LABEL: The LABEL parameter tells the system the name by which your file 
is identified on disk. 

If the file is being created, the name you supply in the LABEL parameter is used 
to identify the file on disk. If you omit the LABEL parameter from a disk FILE 
statement, the name from the NAME parameter is used. 

If the file is an existing disk file, you must supply a LABEL parameter when the 
name your program uses to refer to the file differs from the name by which the 
file is identified on disk. 

Several versions of a file can be created on the same disk and be given the same 
name. If the TRACKS or RECORDS parameter you are using in creating a file 
is the same as the TRACKS or RECORDS specified for an existing file you must 
specify LOCATION. You can reference each of these files by its name and date, 
or by its name and location on disk. Both date and location must be unique for 
each version. (See Examples 2 and 4 and File Processing Considerations.) 


The keyword for the parameter is LABEL. It must be followed by the name of 
the file on disk. The name can be any combination of characters except commas, 
quotes, or blanks. The first character must be alphabetic. The number of char¬ 
acters must not exceed 8. The LABEL parameter for a file named PAYROLL is 
coded in the following example. 



TRACKS or RECORDS: The TRACKS or RECORDS parameter is needed for 
files that are being created. The parameter tells the system the amount of space 
needed on disk for the file. 

If you use the TRACKS keyword, you specify the number of disk tracks needed 
for the file. 

If you use the RECORDS keyword, you specify the approximate number of 
records for the file. The total space allocated will be rounded up to full tracks 
allowing adequate space to accomodate at least the number of records indicated. 
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Either of these two keywords, TRACKS or RECORDS, can appear in the FILE 
statement, but not both. The keyword must be followed by a number indicating 

the amount of space needed. 





DISK FILE STATEMENT (continued) 


If TRACKS is used, the humbef fttufct Be within the range 1-398 if you are using 
full capacity 5444 disk If you are using half capacity 5444 disk packs, the 

number must be within tfYS 1-198. If you are using 5445 disk packs, the 
number must be in the reiff§l' Of 1 -3980. The following example shows how the 
TRACKS parameter fdr^vftl^ii^iuiring 20 tracks is coded. 




>■■■■■■■ ■■■■ ■■■■KJiMiiooMOCxnxffiaBgffl ranutMuooeioaia 


LOCATION: The LOCATION parameter is not required. It can, however, be 
used for files that are being created. LOCATION is required when creating 
several versions of a file or when loading an offline multivolume file to packs 
which contain other files. (See Example 4.) It can also be used in referencing 
one of several files housing the same name and same size. LOCATION is not 
required if sizes differ. 


For files that are being crfcafikJ, the parameter tells the system the number of the 
track on which the file is to begin. If it is omitted, the track is chosen for you. 


For files that are being refertn|3e&, the parameter tells the system the number of 
the track on which the file Ih this case, the system uses the track number 

to tell one file from another. 

The keyword for this parameter is LOCATION. For the 5444 disk the 
LOCATION format is: 


LOCATION-track number 


Trljck number must be between 
£-20$ (half-capacity disk) or 

(full-capacity disk). Tracks 
C yi are reserved for the system. 


For the 5445 disk the LOCATION format is: Slash is needed to separate 

1 1 — — cylinder number and track 

LOCATION-cylinder number/track number number (when both are 

^ V specified 

Cylinder number must be - Track number must be betwee 

between 1-1$$. Cylinder 0 Track number 0 is assumed if 

is reserved fdr the system. number is not specified. 

Split cylinder file support on the 5445 disk allows for an additional 
LOCATION parameter: 


Track number must be between 0-19. 
Track number 0 is assumed if track 
number is not specified. 


LOCATION-file name 


For a discussion on how the LOCATION parameter is used when 
specifying split cylinder fitii, see Split Cylinder Files. 
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DISK FILE STATEMENT (continued) 

RETAIN: The RETAIN parameter is used to classify files according to their use: 
scratch, temporary, or permanent. 

A scratch file is normally used only once in a program and not retrieved after 
the program has ended. A scratch file cannot be used as an input file unless 
RETAIN-A is specified, however, a scratch file can be retrieved if a previous pro¬ 
gram has defined it as a permanent or temporary file and then redefined it as a 
scratch file. To change a permanent file to a scratch file you must use a utility 
program. A temporary file can become a scratch file by using a utility program 
or by using a RETAIN-S parameter. A RETAIN-A parameter is needed to change 
a scratch file to a temporary file. A scratch file cannot become a permanent file 
unless it becomes a temporary file first. A temporary file can be changed to a 
permanent file only if the file name is changed and copied as a permanent file. 

The system will overlay a scratch file if the disk pack is full and/or file space 
is needed by a new file or by a system program. 

A temporary file is usually used more than once. The area containing a temporary 
file can be only given to another file under one of the following conditions: 

1. A FILE statement containing the RETAIN S parameter is supplied for the 
temporary file. This converts the temporary file to a scratch file. 

2. Another file with the same LABEL name is loaded into the exact area 
occupied by the temporary file but this only changes the data. Space and 
location parameters are required. 

3. The File Delete program is used to delete the file. 

The area containing a permanent file cannot be used for any other file until the 
File Delete program has deleted the permanent file. 

A disk file is classified as scratch, temporary, or permanent when it is created. 

If the RETAIN parameter is omitted from the FILE statement when the file is 
created, the file is assumed to be a temporary file. The RETAIN parameter may 
be omitted when accessing an existing file; however, RETAIN-A must be coded 
to reactivate a scratch file which changes to a temporary file. 

The keyword for the parameter is RETAIN. It must be followed by a code that 
indicates the classifications of the file. The codes are: 

Code Meaning 

S Scratch file 

T Temporary file 

P Permanent file 

A Reactivate scratch file 

The RETAIN parameter for a permanent file is coded as follows: 
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DISK FILE STATEMENT (continued) 


DATE: The DATE parameter tells the system the date of a file. It is used to 
ensure that the proper version of the file is referenced. 

When a file is created on disk, its LABEL name and creation date are written on 
the disk as identification. The system date is the date used. (The system date 
is explained under DA TE Statement.) More than one file on a disk can be given 
the same name. The creation dates of these files must, however, be different. 

To reference such a file, you can use its name and date (see Example 4), or its 
name and location on disk. If neither the date nor the location is given, the file 
having the latest date is the one automatically referenced. 

The keyword for this parameter is DATE. It must be followed by a 6-digit 
number representing the date (two more spaces are allowed for punctuation 
delimiters). 

The date can be coded in one of two forms: month-day-year (mmddyy) or 
day-month-year (ddfnmyy). You must specify the form when the system is 
generated. The date you specify in the DATE parameter must be in that form. 
The date can be coded with or without punctuation. For example, July 31,1971, 
might be coded in any one of the following ways: 

073171 

310771 

07/31/71 

31/07/71 

Month, day, and year must each be 2-digit numbers but lead zeros in month and 
day may be omitted when punctuation is used (7-31-71 or 31-7-71). A blank, 
comma, number, or quote cannot be used to punctuate the date. 

To illustrate this parameter, assume that two versions of a file are written on the 
same disk. In the next example are the NAME, LABEL, and DATE parameters 
for two versions of a file on the same disk, one written on April 5,1971, the 
other on August 3,1971. Both files have the same label: F0001. 
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HI KEY: The HI KEY parameter must be used when you define a multivolume 
indexed file. The highest keyfield for each pack must be entered. For further 
information and an example of HIKEY see Multivolume Files under Using OCL 

SPLIT: The SPLIT parameter is used when creating and maintaining split 
cylinder files on a 5445 disk. For further information on SPLIT see 
Split Cylinder Files. 
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DISK FILE STATEMENT (continued) 


Examples The following are examples of FILE statements. In each example, the file is 

described first, then the corresponding FI LE statement is shown. 


Example 1: Suppose that each week you create a disk file that contains the 
records for the transactions you had made that week. Assume the following 
facts about that file: 

— The name your program uses to refer to the file is TRANS, which is also 
the name you want to use to identify the file on disk. 

— You are placing the file on a removable disk named VOL03. 

— You intend to mount the disk on drive one. 

— You want to save the file for use at the end of the month. 

— The file contains 225 records. 

— You are letting the system choose the disk area that will contain the file. 

The following example shows how the FILE statement for the preceding file is 
coded when using a 5444 disk. 
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The FILE statement when using a 5445 disk would be: 
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Example 2: Suppose you had created, on the same disk (VOL03), four versions 
of the transaction file described in the preceding example—one for each of the 
weeks in February, 1970. Assume the following: 

— You had created the files on the following days: 2/6/70, 2/13/70, 
2/20/70, and 2/27/70 (these were the system dates used for each of the 
files). 

— You want to reference the third file (the one created 2/20/70). 

— You intend to mount the disk on drive one. 

The file statement you would need is: 
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DISK FILE STATEMENT (continued) 


Example 3: Suppose at the end of the month you combine the files referred 

to in Example 2, for use in preparing your monthly bills. Further assume the 

following: 

— Your program uses the name TRANS to refer to the file, but you want to 
use the name BILLING to identify the file on disk. 

— You are expressing the amount of disk space as the number of tracks re¬ 
quired to contain the file (assume the number is 15), and you want the 
file to begin on track 8. 

— You are placing the file on a removable disk named VOLOI. 

— You intend to mount the disk on drive one. 

The following example shows the FILE statement you would use for this file. 
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Example 4: Suppose you want to create two versions of two files on disk and 
later to access one version of each file. Further assume the following: 

- The names your program uses to refer to the files are AA and BB, which 
are also the names you want to use to identify the files on disk. 

- File AA is being placed on a fixed disk on drive two named FIXED2. 

— File BB is being placed on a removable disk named REM5. 

— You intend to mount the disk on drive two. 

- One version of each file is created on 5/11/70 and 5/12/70. 

— Disk space and location for the files are: 


File 

Version 

Tracks 

Location 

AA 

5/11/70 

10 

200 


5/12/70 

10 

210 

BB 

5/11/70 

20 

200 


5/12/70 

20 

220 


You want to access file AA, version 5/11/70 and file BB, version 5/12/70. 
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DISK FILE STATEMENT (continued) 

The following OCL statements are needed to create the above versions of files 
AA and BB and to access a version of each file. 
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File Processing Considerations — LOCATION and space (TRACKS or RECORDS) must be specified when 

you are reloading an existing temporary file. 

— If you are referencing a file by the DATE parameter and space is given, the 
space must be equal to the space given when that file was created. 

— If you are accessing a file by the LOCATION parameter and space is given, 
the space must be equal to the space given when that file was created. 

— You can create several versions of a file with a program by changing the 
locations of the files and using different system dates. 

— You can create different versions of a file without LOCATION if the space 
parameters as well as the system dates are different. 

— The system assumes that a new file is being created if space is given without 
LOCATION or DATE and the given filename was found but its space does 
not match. 

— The DATE parameter is only allowed for accessing existing files. 

— Whenever a load is performed to an existing file, the system date replaces 
the previous date for that file. 

— if a RETAIN parameter is not specified when reloading an existing file, 
the existing file classification is retained. 

— When a scratch file is created, it is not entered in the Volume Table of 

Contents (VTOC). After the job that created the file is run, the file is lost. 
The way that an S retain type can appear in the VTOC is to change a T 
entry to an S by using RETAIN-S in the FILE statement, or to ciiange a T 
or P entry to S by using a $DELET SCRATCH statement. 
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TAPE FILE STATEMENT 


Function 


Placement 


Format 

Contents 


The FILE statement supplies the system with information about tape files. The system 
uses this information to read records from and write records to tape. 

You must supply a FI LE statement for each new tape file that your program creates, 
and for each existing tape file that your program uses. The FILE statement must 
follow the LOAD or CALL statement and precede the RUN statement. 

// FILE parameters 

All parameters are keyword parameters. The parameters are as follows (keywords 
are in capital letters): 

- NAME-filename (in program) 

— UNIT-code 

{ name 
NL 
NS 

- LABEL- ( filename (on tape) 

\ 'character string' 

— DATE-date 


RETAIN-code 
- BLKL-block length 


RECL-record length 
RECFM-code (record format) 


END-position of tape after processing 


DENSITY- 


1600 

800 

556 

200 


ASCII- 

DEFER- 

CONVERT- 

TRANSLATE- 

PARITY- 


( YES 
j NO 

\ YES 
j NO 

\ OFF 
] ON 

\ OFF 
\ ON 

{ ODD 
j EVEN 
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TAPE FILE STATEMENT (continued) 


The NAME and UNIT parameters are always required. The others are required only 
under certain conditions. 

NAME: The NAME parameter is required. It tells the system the name that your 
program uses to refer to the file. The NAME parameter must be placed on the first 
card or line if two or more cards or lines are used for the FILE statement. (See 
General Coding Rules for rules on continuation.) 

For the Tape Sort program, you must use specific names for files. 


File 

Name 

Input 

INPUT 

Output 

OUTPUT 

Work 

WORK1 


WORK2 


WORK3 


WORK4 (optional) 


For the Dump/Restore program, you must use the name BACKUP in the name 
parameter. The keyword for the parameter is NAME. It must be followed by 
the filename used by the program. The first character of the NAME must be 
alphabetic. The remaining characters can be any combination of characters 
except commas, apostrophes, or blanks. The number of characters cannot 
exceed 8. The following example shows how the NAME parameter for a file 
named FICAOUT would be coded: 


OCL STATEMENTS 
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UNIT: The UNIT parameter is required. It tells the system the tape unit that 
contains or will contain the file. The keyword for this parameter is UNIT. It must 
be followed by a code that indicates the unit. The codes are as follows: 


T1 Tape unit one 

T2 Tape unit two 

T3 Tape unit three 

T4 Tape unit four 


The previous example shows how the UNIT parameter would be coded for a file 
that resides on tape unit two. 
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TAPE FILE STATEMENT (continued) 


REEL: The REEL parameter is required for tape input files and optional for 
output files. It identifies the tape that contains or will contain the file. The 
system uses this parameter to ensure that the correct tape is being used. (For 
information about how a tape is initialized and identified, see Tape Initialization 
in Part II of this manual.) 

The REEL parameter can be coded as follows: 

REEL-nnnnnn This format is used for labeled tape volumes. The volume is 
identified by coding a maximum of six characters, excluding 
commas, apostrophes, and blanks. NS and NL have special 
meanings and may not be used as the name of the reel. 

REEL-NL This coding indicates a tape file without a label. The first 

record of an unlabeled tape must not be an 80-byte record 
beginning with VOL1. 

REEL-NS This coding indicates an input tape file with a non-standard 

label. These labels do not adhere to the IBM Tape Label 
Standard. The first record of a non-standard labeled tape must 
not be an 80-byte record with VO LI as the first four characters. 
REEL-NS is invalid for output files. 

If the REEL parameter is not specified for an output file, the system assumes the 
output tape contains standard labels. If REEL-NS or REEL-NL is used, the LABEL, 
DATE, and RETAIN parameters may not be entered. 

Note: User labels are file labels that follow standard header and trailer label conventions 
(ANSI or IBM). They are a variation of standard labels with a partially fixed format. 
These labels are sometimes provided by other systems. User labels are not checked by 
System/3 tape data management and may not be written as part of the label group. 

The example under NAME shows how the REEL parameter would be coded for a file 
on a tape named TAPE1. 

LABEL: The LABEL parameter tells the system the name (label) of the tape file as 
it exists in the header label. 

For file creation, the name you supply in the LABEL parameter is used in the header 
label. If you omit the LABEL parameter, the name from the NAME parameter is used 
unless REEL-NS or REEL-NL is also specified. Up to eight characters may be supplied 
in the LABEL parameter. 

For existing files, you must supply the label parameter if the name in the tape label is 
different from the name your program uses to refer to the file (the NAME parameter). 

If the header label contains a name longer than eight characters, only the first eight 
characters are recognized by the system for comparison. 

The LABEL parameter may not be used with the parameters REEL-NS or REEL-NL. 
The LABEL parameter can be coded as follows: 

LABEL-name The name entry must begin with an alphabetic 

character and the remaining characters must not be 
commas, apostrophes, or blanks. 
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TAPE FILE STATEMENT (continued) 


LABEL-'character string' A label may also be identified using special characters. 

The character string must be enclosed in apostrophes, 
may not contain commas, and is restricted to eight 
characters in length. If an apostrophe is used as a 
character, it must be coded as two apostrophes. 

DATE: The DATE parameter tells the system the creation date of an input file. 

It is used to ensure that the proper version of the file is used. The date specified 
is compared against the creation date contained in the file label. No comparison 
is done when DATE is not specified. 

For output files, the system date is always used as the creation date. If the DATE 
parameter is specified for an output file, the system compares the specified date 
with the creation date of the file already on the tape. If no file exists on the tape, 
or a file with a different label exists, or the dates do not agree, the system halts. 

The date may be coded in one of two formats: month-day-year (mmddyy), or 
day^month-year (ddmmyy). The format must match the format of the system 
date chosen at system generation time. 

The DATE parameter may not be specified with REEL-NS or REEL-NL. 

RETAIN: The RETAIN parameter specifies the number of days a file should be 
retained before it expires. This number may be from 0 to 999. After the number of 
days has elapsed, the file expires and the system allows the file to be written over. 

If the RETAIN parameter is omitted, a value of zero is assumed. A value of 999 
indicates a non-expiring permanent tape file. 

If an attempt is made to write over an unexpired file, the system halts, allowing 
the operator to cancel the job or continue. A tape containing a permanent tape file 
must be reinitialized before it can be used for output. The RETAIN parameter may 
not be used with REEL-NS or REEL-NL. 

BLKL: The BLKL (block length) parameter specifies the number of bytes in a 
physical block on tape. The block length can be from 18 bytes to 32,767 bytes. 

The maximum length is limited to the main storage not occupied by the program 
and supervisor. The block length must be an integral multiple of the record length 
for fixed (F) and fixed blocked (FB) files (see RECFM parameter). If an ASCII 
file is being used, any existing block prefixes must be included in the block length. 

RECL: The RECL (record length) parameter specifies the number of bytes in a 
logical record. The maximum record length is 32,767 bytes. The minimum record 
length permitted for F and FB type files is 18 bytes (see RECFM parameter). 

The record length for V, VB, D, and DB type files must include the four-byte 
record descriptor. 
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TAPE FILE STATEMENT (continued) 


RECFM: The RECFM (record format) parameter identifies the format of the input 
or output file records. The parameter entries are: 

F — Fixed length, unblocked records. Logical and physical records are the same 
size. 

V — Variable length, unblocked records. Each physical record contains one 
logical record; the logical record can vary in length. 

D — Variable length, unblocked records in the D-type ASCII format. 

FB — Fixed length, blocked records. All records are of equal length and all blocks 

are of equal length. Each physical record contains more than one logical 
record. 

VB — Variable length, blocked records. Each physical record contains logical 
records of various lengths. 

DB — Variable length, blocked records in the D-type ASCII format. 

END: The END parameter specifies the position of the tape after the file has been 
processed. The options are as follows: 

LEAVE — The tape remains in the position it was in after the last record was 
read or written. 

REWIND — The tape is rewound to the load point. 

UNLOAD — The tape is rewound and unloaded for removal from the tape drive. 

If the END parameter is omitted, REWIND is assumed. 

DENSITY: The DENSITY parameter is used to specify the number of BPI (bits per 
inch) at which files are to be written or read. The parameter must specify the density 
at which the tape was initialized. See $TINIT (Tape Initialization Program) description in 
this manual. For nine track tapes this parameter affects only the density of non-labeled 
output files. When standard labeled or non-standard labeled tapes are used, the tape 
hardware will automatically determine the density at which the tape was initialized. 

When a tape is initialized to 1600 bpi with standard labels, any file that is written on 
that tape will be in 1600 bpi, regardless of the parameter specified for DENSITY. 

No error halts will occur if an incorrect nine track density is specified. The parameter 
entries are: 

1600 — The file is to be written at 1600 bits per inch (valid for all nine track 
tape units). 

800 — The file is to be written or read at 800 bits per inch (valid for nine track 
dual density tape units or for all seven track tape units). 

556 — The file is to be written or read at 556 bits per inch (valid for all seven 
track tape units). 
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200 — The file is to be written or read at 200 bits per inch (valid for all seven 
track tape units). 

If the DENSITY parameter is omitted, 1600 bits per inch is assumed on nine 
track tape units, and 800 bits per inch is assumed on seven track tape units. 

ASCII: The ASCII parameter (ASCII-YES or ASCII-NO) is used to indicate to the 
system when an ASCII file is being used. If ASCII files are being used. ASCII-YES 
must be coded. ASCII-YES is invalid for files on seven track tape units. If this 
parameter is omitted or coded ASCII-NO, an EBCDIC file is assumed. 

DEFER: The DEFER parameter (DEFER-YES or DEFER-NO) tells the system 
whether the file will be mounted on a tape drive when the file is allocated and 
opened. If the tape volume is not online, DEFER-YES must be coded. If the 
parameter is omitted, DEFER-NO is assumed. 

Note: For RPG II object programs, this option should only be used for files 
that use the same drive as a table file. All other files are allocated and opened at 
the beginning of the program. 

Other programs (such as COBOL object programs) which do not allocate and 
open all files at the same time, or which do so conditionally by program logic, 
should not use the DEFER-YES option. 

CONVERT: The CONVERT parameter tells the system whether the data converter 
will be turned on or off. This parameter is valid only for seven track tape files. 
CONVERT-ON causes seven track data to be processed in eight bit binary form. 

The convertor writes three main storage characters as four tape characters, and 
converts the opposite way when reading. CONVERT-ON must be specified when 
processing variable length records on seven track tape files. Specifying both 
CONVERT-ON and TRANSLATE-ON is invalid. If this parameter is omitted, 
CONVERT-OFF is assumed. 

TRANSLA TE: The TRANSLATE parameter tells the system whether the data 
translator will be turned on or off. This parameter is valid only for seven track 
tape files. TRANSLATE-ON causes seven track data to be processed in six bit 
BCD form. The translator writes eight bit EBCDIC main storage characters as 
six bit BCD tape characters and translates the opposite way when reading. 
Specifying both TRANSLATE-ON and CONVERT-ON is invalid. If this param¬ 
eter is omitted, TRANSLATE-OFF is assumed. 

Note: If CONVERT-OFF and TRANSLATE-OFF are specified, only the six low 
order bits of the main storage character are written on the tape. When reading 
with CONVERT-OFF and TRANSLATE-OFF the two high order bits of the 
main storage characters are set to zeros. 

PARITY: The PARITY parameter is used to specify the parity at which tape 
characters will be processed. This parameter is valid only for seven track tape files. 
Data conversion (CONVERT-ON) is invalid with even parity (PARITY-EVEN). 

If this parameter is omitted, PARITY-ODD is assumed. 



Note: The following are the valid combinations for TRANSLATE, CONVERT, 

and PARITY parameters. 

- PARITY-ODD, TRANSLATE-OFF, CONVERT-OFF 

- PARITY-ODD, TRANSLATE-ON 

- PARITY-ODD, CONVERT-ON 

- PARITY-EVEN, TRANSLATE-OFF, CONVERT-OFF 

- PARITY-EVEN, TRANSLATE-ON 

SEVEN TRACK CONSIDER A TIONS 

1. CONVERT, TRANSLATE, PARITY, and/or DENSITY must be specified 
for an input file if other than the default parameters were specified for 
output when the file was built, otherwise, tape runaway or data check occurs. 

2. If an output file has REEL-NL on the file card, the reel must have been 
initialized with REEL-NL by the $TINIT (Tape Initialize) program, other¬ 
wise, tape runaway or data check occurs. 

3. If an output file has REEL-NL on the file card and there is a file existing 
on the tape, tape runaway or data check will occur if TRANSLATE, 
CONVERT, PARITY, and/or DENSITY parameters for the new file do 

not match the characteristics of the old file. The tape should be reinitialized 
using $TINIT with REEL-NL if this occurs. 


i 
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BSCA STATEMENT 


Function 


Placement 


Format 

Contents 


The BSCA statement allows you to change all BSCA line specifications in your 
program. This allows the use of either BSCA line without recompiling the program. 
If the BSCA statement is not entered, the line specifications in the program are not 
changed. 

The BSCA statement must follow the LOAD or CALL statement and precede the 
RUN statement. 

// BSCA parameter 

The parameter is a keyword parameter. The parameter is LINE-code. The codes are 
as follows: 

Code Meaning 

1 Change all BSCA line specifications to BSCA line one. 

2 Change all BSCA line specifications to BSCA line two. 
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CALL STATEMENT 


Function 


Placement 


Format 

Contents 


Example 


CALL statements are needed only when you want to merge procedures into the 
job stream. 

To understand the funtion of the CALL statement, you must understand the 
relationship between the job stream and procedures. The job stream contains 
the OCL statements that control the system. The system reads it either from 
cards or the printer-keyboard. Procedures are sets of OCL statements in a source 
library on disk. They have no effect on the system until they are merged into 
the job stream. 

You can modify the procedure identified by a CALL statement, by providing 
other OCL statements (procedure override statements, see Changing Procedure 
Parameters) after the CALL statement. These statements temporarily modify the 
procedure. The last statement of the CALL sequence must be a RUN statement. 
The RUN statement is required, however, whether or not you supply other OCL 
statements. (Procedures are further explained in Procedures.) 

CALL statements can be used in the job stream or in a procedure. They are, in 
effect, replaced by the procedures they identify. The last statement of the CALL 
sequence must be a RUN statement. 

// CALL procedure-name,unit 

Procedure-name: The procedure-name is the name that identifies the procedure 
in the source library. You supply the procedure-name in the Library Mainten¬ 
ance control statements when you use the program to place the procedure in the 
library. (See Library Maintenance in Part 11 of this manual for restrictions on 
procedure-name.) 

Unit: The unit parameter is a code. The code indicates where the disk that con¬ 
tains the procedure is located on the disk unit. The codes are as follows: 


Code Meaning 

R1 Removable disk on drive one 

F1 Fixed disk on drive one 

R2 Removable disk on drive two 

F2 Fixed disk on drive two 


There is no CALL statement example here. The following section. Procedures , 
contains CALL statement examples. 


Statement Descriptions 51 





PARTITION STATEMENT 


Function 

The PARTITION statement is used only in DPF systems and guarantees a minimum 
size to program level two for a program in that level. 

Placement 

The PARTITION statement can be placed anywhere among the OCL statements 
preceding the RUN statement. 

Format 

//PARTITION size 

Content 

Size: The size parameter specifies the number of bytes of storage needed for 
program level two. (See Loading Programs in a DPF Environment.) 

LOCKOUT STATEMENT 


Function The LOCKOUT statement is used only in DPF systems. 

It is used to suspend the other program level to allow fast job initiation in the 
program level in which it is entered. Job initiation is slowed if both program 
levels use the system transient area and/or disk drive one. The other program 
level remains suspended until job initiation is complete. 

Note: This statement should not be used when the active program level is using 
time dependent devices such as BSCA and serial I/O channel. 

Placement The LOCKOUT statement can be placed anywhere among the OCL statements, 

but must precede the RUN statement. 

Format // LOCKOUT 

Content None (Comments may be entered starting in column 12.) 
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PROCEDURES 

Procedures are sets of OCL statements in a source 
library on disk. Procedures can be put into the 
source library by using the Library Maintenance 
program. (See Part II of this manual. Library 
Maintenance, Copy Function , Reader-to-Disk.) 
Procedures must contain one and only one, LOAD state¬ 
ment. All other OCL statements except /& are allowed 
in procedures. The CALL statement is allowed only in 
nested procedures (see Nested Procedures). Object pro¬ 
grams loaded from cards (LOAD*) are not allowed 
in procedures. The object programs are loaded 
from the system input device. However, LOAD* 
statements are allowed in procedures. 

A maximum of 25 utility control statements can 
be included in procedures for the utility programs. 

The utility statements must follow the OCL state¬ 
ments in the procedure. (See Library Maintenance , 

Part II of this manual.) A RUN statement must be 
the last OCL statement in the procedure to separ¬ 
ate the OCL statements from the utility control 
statements. The RUN statement in the job stream, 
rather than the one in the procedure, causes the 
system to run the program. 

An example of a procedure is shown in Figure 9. 

This procedure will be referred to in all of the 
following examples. Assume that the name of the 
procedure is PROC1. The procedure-name is the 
name that identifies the procedure in the source 
library. Further assume that the procedure is 
contained on the fixed disk on drive one (FI). 


Normal Procedure Call 

To merge the procedure (unchanged) into the job 
stream, the statements in Figure 10 would be used 
in the job stream. 
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Figure 10. Normal Call for Procedure 


Changing Procedure Parameters 

You can change any of the parameters in any of the 
statements in the procedure for one job, by placing 
procedure override statements between the CALL 
and RUN statements. Procedure override statements 
modify the procedure for one job only. For example, 
assume you wanted to make the following changes 
to procedure PROC1 (see Figure 9): 

• In the first FILE statement (NAME-DALTOT), 
change the RECORDS parameter from RECORDS- 
1500 to RECORDS-1750. 

• Change the parameter in the SWITCH statement 
from XXX01XX0 to XXX10XX1. 

Figure 11 shows the statements needed in the job 
stream to call and modify PROC1. Note that the 
NAME parameter is also supplied in the FILE state¬ 
ment. This is necessary to identify the FILE state¬ 
ment to which the change applies. 
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Figure 11. Call for Procedure: Changing Parameters 


Delete a Procedure Parameter 

Besides changing a parameter you can delete a para¬ 
meter in a procedure statement entirely if it is a 
keyword parameter. To delete a parameter in any 
of the statements you must code the keyword and 
the hyphen and follow them immediately with a 
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Figure 9. Procedure Example 
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comma. The statement in Figure 12 deletes the 
RETAIN parameter completely. 
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Figure 12. Deleting a Procedure Parameter 


Adding a Statement 

You can add statements to the procedure by plac¬ 
ing the statements you are adding between the 
CALL and RUN statements. For example, assume 
that you wanted to add a NOHALT statement to 
the procedure. Figure 13 shows the statements 
needed in the job stream. 



Add Missing Parameter 

You can omit any of the parameters from all OCL 
statements in a procedure. If you do, you must 
supply the missing parameters between the CALL 
and RUN statements. For example, assume that 
the procedure contained the LOAD statement 
shown in Figure 14. The statements in Figure 15 
would be needed in the job stream to run the 
ENDMON program. Note that the entire LOAD 
statement did not have to be supplied. Only the 
missing parameter was included. 
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Figure 14. LOAD Statement Missing a Parameter 
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Figure 15. Call for Procedure Supplying a Missing Parameter 


Example 

Procedure override statements are printed on the 
logging device along with the statements in the 
job stream. Assume that the statements in Figure 
16 are used in the job stream. The statements 
from the procedure would be merged with the 
preceding statements and printed as shown in 
Figure 17. 

Statements preceded by XX represent the pro¬ 
cedure statements as they appear in the source 
library. The CALL and RUN statements and 
any statements which are intended as overrides to 
procedure statements or additions to the procedures 
begin with //. 
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Figure 16. Call for Procedure Example 


// CALL PR0C1, FI 
XX LOAD ENDMON,R2 

XX FILE NAME-DALTOT,UNIT-F2»PACK-V0L04»RECORDS-1500,RETAIN-R 
// FILE NAME-DALTOT,REC0RDS-1750 

XX FILE NAME-ACCTOT,LABEL-TOTAL,UNIT-Rl,PACK-V0L02,DATE-01/04/71 

XX SWITCH XXX01XX0 

// SWITCH XXX10XX1 

// NOHALT 

XX RUN 

// RUN 


Figure 17. Printout of Sample Case 
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Nested Procedures 

Some procedures are done in the same order every 
time a job is performed. Nesting procedures is a 
convenient way to link the procedures together 
and requires you to call only the first procedure. 
Each procedure will call the next procedure until 
the job has been completed. 

By nesting procedures together several benefits can 
be realized. 

• Programs are always run in the correct sequence. 

• Operator intervention (and chance of operator 
error) is decreased. 

• File space can be saved. Files used to pass data 
from job to job can be scratched after the last 
program. 

• Files are less likely to be destroyed by running 
nonrelated programs between programs of a job. 


By using nested procedures these control statements 
could be stored on disk and the job could be per¬ 
formed by calling only one procedure. Figure 18 
shows the three procedures needed to perform the 
copy job described. There is only one CALL state¬ 
ment necessary in the job stream from the system 
input service. 

This CALL statement links the job stream to a 
master procedure (CPYF22) which is used to call 
the procedure necessary to perform the job. 

CPYF22 contains three CALL statements that call 
the three procedures necessary to copy F2 to R2. 
Notice that CPYF22 contains only CALL statements. 
Any procedure within nested procedures can consist 
entirely of CALL statements and does not need a 
RUN statement to indicate the end of the procedure. 
Nested procedures allow you to have an unrestricted 
number of CALL statements in a procedure. There¬ 
fore CPYF22 could have more then three CALL 
statements if you felt it necessary To add any pro¬ 
cedures. 


Here is an example of how nested procedures might 
be used. Suppose you want to back up a fixed disk 
pack containing files which will be used in the 
future. The OCL statements and utility control 
statements to copy one disk pack (F2) to another 
disk (R2) would look like this if nested procedures 
were not used: 
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System Input Device 


// CALL CPYF22,F1 


// RUN 


Level 1 


Level 2 


K 


\ 


- 

CPYF22 


//CALL DEALIB,F1 

\l 

// CALL DEALF1,F1 

\ 

// CALL CYF2R2,F1 

\ 


DEALIB 


Figure 18. Nested Procedures 
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// LOAD $MAINT,F1 
// RUN 

// ALLOCATE 


DEALF1 


// LOAD $DELET, FI 
// RUN 
// REMOVE 
// END 


CYF2R2 


// LOAD $COPY,F1 
// RUN 

// COPYPACK.. . 

// END 


Figure 19 is an inventory application of nested 
procedures. A company issues daily reports on 
goods bought and sold by calling the DAY pro¬ 
cedure. By nesting procedures together a daily 
report and a weekly report can be written by 
calling the WEEK procedure. Once a month 
// CALL MONTH is used to write out daily, weekly, 
and monthly reports. Finally, monthly, weekly, 
daily, and yearly reports are written once a year by 


calling the YEAR procedure which nests all of the 
other procedures together. 

No more than nine levels of CALL procedures can 
be nested together. Levels of procedures are deter¬ 
mined by the number of CALL statements away 
from the system input device a procedure is 
located. For instance, in Figure 19 when // CALL 
YEAR is given in the system input device, the 


//CALL YEAR //CALL MONTH //CALL WEEK //CALL DAY 



Figure 19. Inventory Example 
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YEAR procedure would be one level away from 
the system input device. MONTH and END1 pro¬ 
cedures are two levels away from the system input 
device when // CALL YEAR is given. 

By using nested procedures, fewer control state¬ 
ments are needed in the job stream from the 
system input device. However, certain rules must 
be followed to make nested procedures work: 

1. No more than nine levels of procedures are 
permitted. 

2. Each procedure may have an unrestricted num¬ 
ber of CALL statements to the next level of 
procedures. 

3. Only utility control statements can follow a 
RUN statement. 


4. Procedure additions or overrides supplied between 
the CALL and RUN statements in the job 
stream are merged between the first LOAD and 
RUN statements encountered in the procedures 
(see Example of Nesting Procedures). 

5. Any OCL statements permitted before the RUN 
statement in the job stream are also permitted 
anywhere before the RUN statement in a pro¬ 
cedure (see Example of Nesting Procedures). 

Example of Nesting Procedures 

Suppose you want to decrease operator intervention 
by using the NOHALT statement. In Figure 18 the 
NOHALT statement could be placed between the 
CALL and RUN statements in the system input 
device. In this case it would be read as an additional 
OCL statement for the DEALIB procedure. 

However, it could be placed anywhere in the master 
procedure, CPYF22, or anywhere before the RUN 
statement in the DEALIB, DEALF1, or CYF2R2 
procedures. The rule would still be followed no mat¬ 
ter what procedure contained the additional OCL 
statement. 


Statement Descriptions 
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USING OCL 


This section is designed to aid you in your use of OCL. The topics described in this 
manual involving the use of OCL are: 

• Compiling an RPG II program 

• Processing a card file 

• Creating and processing a disk file 

• Processing two disk files 

• Processing large indexed disk files 

• Processing a disk file that uses external indicators 

• Creating and processing multivolume files 

• Creating and processing split cylinder files 

• Automatic file allocation 

• Storing programs and procedures into libraries 

• Checkpoint/restart 

• Dual programming feature 

• Statement examples 

For a more complete explanation of the statements, their parameters, and coding 
rules refer to Statement Descriptions and Coding Rules in Part I of this manual. 
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COMPILING AN RPG II PROGRAM 

After your RPG II program is written and recorded 
in cards, it must be compiled. To compile an RPG 
II program, two OCL statements are required, 
CALL and RUN. 



V___-_ S 


In the preceding example the first statement, // CALL 
RPG,F1, tells the system to get the procedure that 
loads the RPG II Compiler from the fixed disk. The 
second statement // RUN, tells the system to run the 
compiler program. The source deck may follow the 
RUN statement or be called from disk using a 
COMPILE statement. 

CREATING A DISK FILE 

To create a sequential, direct, or indexed disk 
file you must tell the system the size of the 
file and the use of the file. To state the file 
size (using the FILE statement), two keywords 
are available: TRACKS and RECORDS. You 
may use one or the other, but not both. 

If you use RECORDS, the system calculates the 
disk space required and converts it to tracks for 
you. If you use the TRACKS parameter, there is 
no need for the system to perform these calcula¬ 
tions. 

A file is classified as scratch, temporary, or perma¬ 
nent when it is created. You use the RETAIN para¬ 
meter of the FILE statement to tell the system how 
to classify the use of a file. If you omit the 
RETAIN parameter, the file is assumed to be a 
temporary file. 


For example, you want to create a master file of 
names and addresses. You would code the following: 
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(This master file is classified as permanent.) 
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LOADING AND RUNNING PROGRAMS 
IBM Programs 

Many IBM programs require only two OCL state¬ 
ments, LOAD and RUN. 

The following examples show the OCL cards needed 
to load and run two IBM programs. (The Disk 
Initialization and File Delete programs are discussed 
in Part II of this manual.) 



X// RUN 


/ // LOAD$INIT, FI S 



The Disk Initialization program 
is loaded and run. 



/ U RUN 


/// LOAD$DELET, Fl' 




The File Delete program is 
loaded and run. 


Object Programs Using Card Files 

LOAD and RUN are the only two OCL statements 
needed to load and run RPG II programs that use 
no disk files. To run a certain job, the object pro¬ 
gram must be loaded into storage. To load an ob¬ 
ject program that is on cards (object deck), an * 
must follow the word LOAD. (The * tells the sys¬ 
tem that an object deck follows the RUN state¬ 
ment.) 

For example, only these two statements are re¬ 
quired for a program that prints data from a 
transaction card file. 



Object Programs Using One Disk File 

To load and run an object program that uses a 
disk file, another OCL statement is required: 
FILE. Three items of information must follow 
the word FILE: 

• The name of the file. 

• The name of the disk pack the file is on. 


• The location of the disk pack. 


For example, you want to load and run an object 
program using a disk file named SEQDISK. The 
file resides on removable disk pack named VOLI. 
You would code the following: 
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Object Programs Using More Than One Disk 
File 

One FILE statement is required for each disk file 
used by a program. To load and run an object 
program that uses two disk files, two FILE state¬ 
ments are required. 

In the following example, two disk files are used: 
an input file (INDISK) and an output file (OUT - 
DISK). 
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The first FILE statement contains information 
needed to access the data in that file. The second 
FILE statement contains information needed to 
create an output file. 

Object Programs Using One Disk File and 
External Indicators 

The SWITCH statement is used to set external in¬ 
dicators (U1-U8 on RPG II specifications sheets) 
on or off. External indicators are used to regulate 
when certain functions are performed. 

In the following example,you are running a program 
using one disk file (INVMSTR), an inventory master 
file. 
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In order for the program to perform certain func¬ 
tions, such as updating and output, the first exter¬ 
nal indicator (U1) must be turned on. In the 
SWITCH statement the eight characters correspond 
to the eight external indicators. In this program only 
one external indicator (U1) is used. 


62 





Processing Large Indexed Disk Files 

When additions are made to a large indexed file, the 
amount of time needed to sort the keys of the index 
at end-of-job time may be excessive. This sort time 
can be reduced by using a work file. 

The work file is used to merge the added keys into 
the index, and must be large enough to contain all 
of the keys added to the file. If the program adds 
records to more than one indexed file, the work 
file must be large enough to contain all the keys for 
the file with the greatest number of additions. The 
work file should be located as close as possible to 
the index being sorted. 

If the indexed file is on a 5444 disk, the work file 
must be named $INDEX44 and be located on a 5444 
disk. If the indexed file is on a 5445 disk, the work 
file must be named $INDEX45 and be located on a 
5445 disk. To determine the number of tracks re¬ 
quired for the work file, use the following formulas: 

256 

number of adds *r (key length+3) -r 24 = tracks for 

5444 disk 

256 I 

number of adds -r (key length+4) -5- 20 = tracks for 

5445 disk 

After dividing 256 by keylength+x, the remainder j 
should be dropped. After the other divisions, round 
the quotient to the next highest whole number. 

If the work file is not large enough to contain all the 
index keys, the keys are sorted in the normal manner 
without using the work file. If possible, the work 
file should be located on a different disk drive from 
the indexed file whose keys are being sorted. If this 
is not possible, the work file should be as close as 
possible to the beginning of the file whose keys are 
being sorted. This minimizes the disk seek time. 

The work file can be used with multivolume files. 
However, it cannot be located on a pack that contains 
one of the offline volumes of a multivolume file. The 
pack containing the work file must remain online 
while the job is run. The work file must be RETAIN-S. 
If RETAIN-T or RETAIN-P is specified, the system 
forces it to RETAIN-S. 

For small indexed files of 10 tracks or less where the 
sort time is negligible, a work file will not improve 
performance and should not be used. 


To use this performance option, no change is needed 
to your source program. Also, programs need not be 
recompiled to use this option; only the additional 
OCL FILE statement is needed. 


MULTIVOLUME FILES 


File Statements for Multivolume Files 

If a file is too large for one disk, you can con¬ 
tinue it on one or more subsequent disks. Such 
files are called multivolume files. (A volume is 
one disk.) Multivolume files can be online or 
offline. A file is online if all volumes are 
mounted when the job begins. The UNIT and 
PACK parameters are equal. An offline file has 
fewer UNIT parameters (shares same unit). 

Creation 

The ways that you can create a multivolume 
file depend on the type of file you are creating. 
For a sequential and indexed file, the records 
are stored in consecutive locations on disk, in 
the order that they are read. One disk is filled 
at a time. 

For sequential files, each volume must be 
filled before the next volume is loaded. For 
indexed files, each volume need not be filled. 

Each indexed volume is loaded until a key field 
is reached that is higher than the HI KEY for that 
volume, then the next volume is loaded. Indexed 
files must be loaded in key field sequence. A halt 
occurs if a volume is filled and there is not a 
record with a key field equal to the HI KEY for 
that volume. For example, suppose the HI KEY 
for a volume is 199. You load a record with the 
key field 195. It is less than the HI KEY, so it is 
loaded on the volume. Next, you load a record 
with the key field 200. Record 200 would be 
loaded on the next volume, and a halt would 
occur. The reason for the halt is that you did 
not load a key field record equal to 199 before 
you jumped to a new volume. This halt can be 
ignored. You can load the next volume and at 
some future time insert a key field record equal 
to the HI KEY. To insert a record after the load¬ 
ing sequence has passed, a random add must be 
done. 
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Indexed and sequential files may be either 
online or offline. 

If using removable disks when creating sequential 
or indexed files you can mount a disk, wait until 
the system indicates it is filled, then, mount the 
next disk. If you have two drives, you can mount 
the two disks, wait until the first one is filled, then 
replace it with the third while your program fills 
the second disk. In either case, you cannot use 
more than 40 disks per job. 

Space can be allocated on all volumes of a multi¬ 
volume file if the volumes are online at the time 
of the allocation. Space can also be allocated for 
an offline file, other than the initial volume, but 
the packs must be empty packs or space (TRACKS 
and LOCATION) known to be available. You can 
use both fixed and removable disks with any on¬ 
line multivolume file. Space for a volume of a 
multivolume file will be reserved after one or 
more records are placed in that volume. 

Direct files must be online. Direct files are created 
in a non-consecutive manner. When creating such 
files, you are required to mount all the disks on 
your disk unit at the same time. The maximum 
number of 5444 disks you could use, therefore, is two 
if you have only one drive, or three or four if 
you have two drives. The maximum number of 5445 
disks is one if you have one drive, or two if you have 
two drives. 

Processing 

The ways in which you can process multivolume 
files depend on the method your program uses 
to get records from the file. If records are read 
from a sequential or indexed file, you can mount 
a disk, wait until all of the records have been read 
from the disk, then mount the next disk. If you 
have two drives, you can mount two disks, wait 
until all of the records have been read from the 
first disk, then replace that disk with the third 
while your program reads from the second disk. 

When you are processing files offline the disks must 
be removable. When online, any combination of 
fixed and removable disks is acceptable, but all 
must be mounted and must remain mounted. 


OCL Considerations 

When a file consists of more than one volume, the 
FI LE statement parameters require different coding. 

Multivolume Disk Files 

The FILE statement for multivolume disk files re¬ 
quires that you define and code-additional parameters 
for these keywords: PACK, UNIT, TRACKS, 
RECORDS, and LOCATION. 

These additional parameters are necessary for two 
reasons: 

1. When processing disk files contained on more than 
a single volume, the system requires information 
about each volume in order to perform all the 
protection and checking functions necessary. 

2. Additional information is needed to determine 
and check the sequence in which the volumes 
are processed and when they are to be mounted 
on the disk drives. 

The rules for coding a list of data or codes after a 
keyword are as follows: 

1. The list must be enclosed by apostrophes. 

2. The items in the list must be separated by com¬ 
mas. No blanks are allowed within or between 
items. 

Figure 20 shows an example of lists in parameters. 

The file is online. 

The PACK parameter requires a list. The UNIT par¬ 
ameter may require a list while LOCATION, 

TRACKS, HIKEY, and RECORDS require a list 
if they are stated. The considerations for using the 
lists in these parameters are included in the para¬ 
meter discussions following. The functions of the 
parameters are explained under Disk FILE Statement. 
(Parameters not mentioned here are used as explained 
under Disk FILE Statement) 
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Figure 20. FILE Statement for a Disk Multivolume File 
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FILE STATEMENT PARAMETER CONSIDERATIONS FOR MULTIVOLUME DISK FILES 


PACK 


The names of the disks that contain or will contain the multivolume file must 
follow the keyword PACK. (PACK names must be unique for proper function¬ 
ing.) 

When a multivolume file is created, the system writes a sequence number on the 
disks to indicate the order of the disks. The disks are numbered in the order in 
which you list their names in the PACK parameter. 

When a multivolume file is processed the system provides two checks to ensure 
that the disks are used in the proper order. 

1. It checks to ensure that the disks are used in the order that their names 
are listed in the PACK parameter. 

2. It checks the sequence numbers of the disks used to ensure they are con¬ 
secutive and in ascending order (01, 02, and so on). 

The system stops when it detects a disk that is out of sequence. The operator 
can do one of three things: 

1. Mount the proper disk and restart the system. 

2. Restart the system and process the disk that is mounted if the sequence 
is ascending (for consecutive input and update). 

3. End the program. 

Consecutive input or update sequence numbers are ignored if the file was not 
created as multivolume. If the file is multivolume created and the sequence 
is ascending but not consecutive, a diagnostic halt is given which allows the 
proceed option. 

The following is an example of the PACK parameter for an offline multivolume 
file that is contained on three disks, named VOL1, VOL2, and VOL3. 


1 4_8_12_16_20_24_28 32 36 4Q . 44 48 


7\ 

FF 

Fi 

Lt 

rf 

lAf 

31 

'3 

IF 1 

LI 

z -. i 

JNl 

7- 

Rl 

Lji 


:k- 


/op 

-i. 

v< 


r; 

/Jofl 

pf 

pr 











T " 









7 



.rt: t 































UNIT The keyword UNIT must be followed by a code or codes indicating the location 

on the disk unit that contains or will contain the file. No UNIT parameter may 
be repeated. The codes are as follows: 


Codes 

Meaning 

R1 

Removable disk on 5444 drive one 

FI 

Fixed disk on 5444 drive one 

R2 

Removable disk on 5444 drive two 

F2 

Fixed disk on 5444 drive two 

D1 

Removable disk on 5445 drive one 

D2 

Removable disk on 5445 drive two 
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FILE STATEMENT PARAMETER CONSIDERATIONS FOR MULTIVOLUME DISK FILES (continued) 

The order of codes in the UNIT parameter must correspond to the order of 
names in the PACK parameter. 

A multivolume file must not have one volume on a 5444 disk drive and another volume 
on a 5445 disk drive. All volumes of a file must be on the same type of disk drive. 

When you are creating or processing a sequential or indexed file, you can use 
the same drive for more than one of the disks, however, the disks must then all 
be removable disks. If you do, you must not repeat the code for the drive in the 
UNIT parameter. When the number of codes in the UNIT parameter is less than 
the number of names in the PACK parameter, the system uses the codes alternately. 

For the 5445 the UNIT parameter can have a maximum of two unit codes. 

When two unit codes are given, the volumes must be mounted alternately in 
the order indicated by the unit codes. If all the volumes are to be mounted 
on the same drive, you specify only one unit code. 

If any fixed unit, FI or F2, is specified, the file must be online multivolume. 

Assume that your program processes an offline file consecutively. Further 
assume the following: 


The disks containing the file are named VOLt, VOL2, and VOL3, respectively. 

You intend to mount VOL1 and VOL3 on 5444 drive one, and VOL2 
on 5444 drive two. 


In the following examples, line A shows the PACK and UNIT parameters for the 
file. If all three disks were used on 5444 drive one, the UNIT parameter in line B 
would have been used. 
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TRACKS or RECORDS A keyword, TRACKS or RECORDS, must be followed by numbers that indicate 

the amount of space needed on each of the disks that will contain the multivol¬ 
ume file. TRACKS or RECORDS must be specified. Any multivolume file 
load requires a TRACKS or RECORDS parameter whether the file previously 
existed or not. The order of these numbers must correspond to the order of the 
names in the PACK parameter. For example, assume the following: 


— Your program is creating a sequential (offline) file on three disks: 
VOL1, V0L2, and VOL3. 

— The first 50 records are to be placed on VOL1, the next 500 on VOL2, 
and the last 200 on VOL3. 

The PACK and RECORDS parameters for the file are: 
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FILE STATEMENT PARAMETER CONSIDERATIONS FOR MULTIVOLUME DISK FILES (continued) 


LOCATION The keyword LOCATION must be followed by the numbers of the tracks on 

which the file is to begin on each of the disks you use for the file. The order 
of the numbers must correspond to the order of the names in the PACK para¬ 
meter. For example, assume the following: 

— The disks containing the file are: VOL1, VOL2, and VOL3. 

— The tracks on which the file is to begin on each disk are: track 198 in 

VOL1, tracklO in VOL2, and track 8 in VOL3. 

The PACK and LOCATION parameters for the file are shown in the following 
example. If you omit the LOCATION parameter, the system chooses the be¬ 
ginning track on each of the disks. If LOCATION is specified for one disk, it 
must be specified for all disks. If the multivolume file exists, LOCATION must 
be given for all disks and must be identical to the LOCATION parameters spec¬ 
ified when the file was created. 
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RETAIN RETAIN-S must not be specified unless the file is online multivolume. If 

RETAIN-S is used for online multivolume, it cannot be changed to RETAIN-T 
unless also done online. 

HI KEY The HI KEY parameter is used only for multivolume indexed files. HI KEY 

limits the highest keyfield that can be put on each pack of a multivolume file. 
The following example contains an example of a HI KEY parameter list using 
the file used in example A under Unit In this case the three volumes contain 
lists of names. The highest keyfield allowed on the first volume is JONES. This 
means that all the records beginning with A and including JONES will be pro¬ 
cessed on this volume. Since HI KEY parameters must be in ascending order, 
the next volume should contain all of the records with names following JONES 
and including NICHOL. The last volume will contain all the records with names 
that come after NICHOL. 







FILE STATEMENT PARAMETER CONSIDERATIONS FOR MULTIVOLUME DISK FILES (continued) 


OCL considerations for the HI KEY parameter are: 

1. All characters except commas are valid. 

2. The list of HI KEY parameters must begin and end with an apostrophe 
even if only one parameter is specified. A single apostrophe in a key field 
must be written as a double apostrophe in the HI KEY parameter . 

3. For each PACK parameter specified, there must be a corresponding 
HI KEY keyfield parameter for that pack. 

4. The HI KEY fields must be equal in length and must be specified in 
ascending order. 

5. The maximum length of a HI KEY field is 29 characters. 

6. The HI KEY fields must be the same length as the keys on file. 

7. Continuation of HI KEY sublists must begin in column 4 of the continuation 
card, following the // blank. 

8. Comments must not follow the last comma on a file statement where the last 
parameter is an incomplete HI KEY sublist. 

Packed HI KEY: The packed HIKEY parameter has all the OCL considerations 
for HIKEY including the following restrictions: 

1. The first character following the HIKEY keyword and dash (HIKEY-) must 
be a P to indicate packed HIKEY. 

2. All characters in the packed HIKEY must be zoned numerics (0-9). 

3. The number of digits in each packed key must be the same. 

4. The number of zoned numeric characters per packed HIKEY must not ex¬ 
ceed 15, since the maximum packed key field length is 8. 

The following example shows a packed HIKEY parameter. In the example the 
key field length of MVFILE is 2. The HIKEYs are X'085F', X'092F', and 
X'I08F' for VOL1, VOL2, and VOL3 respectively. The first two packed keys 
required a leading zero to make the lengths consistent. 
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Multivolume Tape Files 

The FILE statement for processing multivolume tape 
files requires that you define and code the UNIT and 
REEL parameters differently than you would for 
single volume files. There are two reasons for this: 

1. When processing tape files contained on more than 
a single volume, the system requires information 
about each volume in order to perform all the 
checking and protection functions necessary. 

2. Additional information is needed to determine 
and check the sequence in which the volumes are 
processed and when they are to be mounted on the 
tape drives. 


For multivolume tape files, the UNIT and REEL 
parameters of the FILE statement may require a list 
of codes. When coding a list of codes, the following 
rules must be followed: 

1. The list must be enclosed by apostrophes. 

2. The .items in the list must be separated by commas. 

3. Nine and seven track units cannot be intermixed. 

The considerations for coding multivolume parameters 
are included in the following parameter discussions. 
The functions of the parameters are explained under 
Tape File Statement. Parameters not mentioned 
here are used as explained under Tape File Statement. 


When an end of volume condition is reached on a 
multivolume file, that volume will rewind to load 
point and unload. The message 'EOV Tn' will be 
printed if LOG is on (where n = 1,2, 3 or 4). If the 
drive that is to contain the next volume (whether 
the same drive or another drive), is not in a ready 
condition, the system will come to I/O attention. 
Processing continues when the drive which is to con¬ 
tain the next volume is made ready. If you are using 
alternating drives, and the next volume is mounted 
and the drive is ready when end of volume is 
reached, the message is printed and processing con¬ 
tinues without stopping. 
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FILE STATEMENT PARAMETER CONSIDERATIONS FOR MULTIVOLUME TAPE FILES 


REEL The names of the tapes that contain or will contain the multivolume file must 

follow the keyword REEL (40 names maximum). If the input tapes are not 
labeled or contain non-standard tape labels, the REEL parameter must be 
coded REEL-'NL,n' or REEL-'NS,n', where n is the number of volumes in the 
file (99 volumes maximum). For output files, the n in REEL-'NL,n' is ignored. 

UNIT The keyword unit must be followed by a code or codes indicating the location of the 

tape unit that contains or will contain the file. No UNIT parameter may be repeated. 
The order of codes in the UNIT parameter must correspond to the order of names 
in the REEL parameter. When the number of codes in the UNIT parameter is less 
than the number of codes in the REEL parameter, the units are used alternately. 

In the following examples, line A shows a tape multivolume file consisting of three 
reels. The volumes must be mounted as follows: 

INVREEL1 on tape unit T1 

INVREEL2 on tape unit T2 


INVREEL3 on tape unit T3 



Line B shows a three-volume file with non-standard tape labels. The volumes must 
be mounted as follows: 

First volume on tape unit T1 

Second volume on tape unit T2 

Third volume on tape unit T1 

Line C shows a three-volume file with unlabeled reels. The volumes must be mounted 
in sequence on tape unit T1. 
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SPLIT CYLINDER FILES 

To use split cylinder file support, two parameters 
(SPLIT and LOCATION) are specified on the FILE 
statement. The SPLIT parameter specifies the size of 
each split cylinder file. It can also be used to specify 
the size of the group of split cylinder files you want 
on disk. The LOCATION parameter determines 
where on the 5445 disk each split cylinder file can be 
found. For further discussion of split cylinder file 
concepts, see IBM System/3 Disk Concepts and 
Planning Guide, GC21-7571. 

Restrictions for Using Split Cylinder Files 

1. Split cylinder files can only be direct or sequential 
files and cannot be multivolume files 

2. Split cylinder files can only be used with the 5445 
disk and not the 5444 disk. 

3. TRACKS or RECORDS parameters must not be 
specified. 

4. Labels must be unique. Therefore, the DATE 
parameter is used only to further qualify the split 
cylinder file. The file date is always the current 
system date for the job. 

5. When processing the file, the block length 
cannot be longer than the space available on 
one cylinder of a split cylinder file. 


Creating the First Split Cylinder File in a Group 

The SPLIT parameter is required when creating the 
first split cylinder file in a group of split cylinder 
files. The LOCATION parameter is optional. 

The SPLIT parameter entries are: 

SPLIT-tracks per cylinder/number of cylinders 

The tracks per cylinder entry specifies the amount of 
space needed on each cylinder for the first split 
cylinder file. The cylinders entry shows the number 
of cylinders needed for the whole group of split 
cylinder files to be specified. 

The LOCATION parameter is optional since the 
system will find a starting location for the split file 
group. However, if you want to specify a particular 
cylinder, you may. 

The LOCATION entries are: 

LOCATION-cylinder number/track number 

The split cylinder file group must always start at 
track 0. Since 0 will always be the entry for track, 
you can omit it from the LOCATION parameter and 
use: 

LOCATION-cylinder number 


File Statement Example: First Split Cylinder File in a 
Group 
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Coding Notes: 


Coding Notes: 


1. On the SPLIT parameter, tracks per cylinder, 
must be 1-19 and the number of cylinders speci¬ 
fied must be 1-199. 

2. On the LOCATION parameter, the cylinder num¬ 
ber must be 1-199 and the track number, if 
specified, must be 0. 

3. LOCATION-5 could be the location entry in this 
example since track 0, the required track entry, 
need not be specified. The LOCATION parameter 
itself is optional. 


1. On the SPLIT parameter, tracks per cylinder must 
be 1-19. 

2. On the LOCATION parameter, the filename must 
be the name of a temporary or permanent split 
cylinder file in the same group. 

Accessing Existing Split Cylinder Files 

To access existing split cylinder files the SPLIT and 
LOCATION parameters are not required. Their use 
would only be needed to further qualify the file 
being accessed. 


Creating Other Split Cylinder Files 

To create the rest of the split cylinder files in a group 
both the SPLIT and LOCATION parameters are 
required. The SPLIT parameter must be in the 
format: 

SPLIT-tracks per cylinder 

This entry, tracks per cylinder, indicates the number 
of tracks needed on each cylinder for the file 
specified. 

The LOCATION parameter must be the filename of 
either the first split cylinder file in the group or any 
other split cylinder file in the group that was created 
in a previous job. 

LOCATION-filename 


File Statement Example: Other Split Cylinder Files 


Loading to Existing Split Cylinder Files 

To load to existing split cylinder files, the SPLIT 
parameter is required and the LOCATION may be 
required or optional. The SPLIT parameter specified 
for loading must agree with the SPLIT parameter of 
the existing split cylinder file. If the format of the 
SPLIT parameter is tracks per cylinder/cylinders, the 
LOCATION parameter is required and must match 
the cylinder number/track number of the existing 
split cylinder file. If the format of the SPLIT para¬ 
meter is tracks per cylinder, the LOCATION para¬ 
meter is optional. 

Scratch Split Cylinder Files 

Split cylinder files may be created as temporary or 
permanent files and in subsequent jobs made scratch 
files. However, the scratch files remain on the 5445 
disk only until the area is needed for the allocation 
of a new file. Then, the scratch split cylinder file is 
deleted. If you have scratched split cylinder files 
and you want to make sure they are not deleted, you 
may reactivate them to temporary files by using a 
RETAIN-A on the FILE statement. 
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AUTOMATIC DISK FILE ALLOCATION 

You can allocate disk space for a file by determining 
the size of the file and the location of an available 
number of tracks that can contain that file. (If you 
have planned the location of your files, you know 
where files are located and the tracks that are 
available for further allocation. The Disk File 
Layout Chart, GX21-9108, is available to docu¬ 
ment your file locations.) After you have deter¬ 
mined where to place your file, you can code the 
LOCATION parameter of the FILE statement to 
tell disk system management on which track the 
file is to begin. Figure 21, part A, is a sample 
FILE statement containing a LOCATION para¬ 
meter to tell disk system management that 
FI LEA is to be located on disk VOL1 beginning 
on track 10. 

If, as in Figure 21, part B, no LOCATION para¬ 
meter is coded, FI LEA is located on the disk pack 
automatically for you. The process used by disk 
system management to allocate file space for you 
is known as automatic file allocation. 

COMPILING A SOURCE PROGRAM AND 
STORING IT IN AN OBJECT LIBRARY 

The COMPILE OCL statement tells disk system 
management to: 


The format of the COMPILE statement looks like 
this: 


// COMPILE SOURCE—name,UNIT— 


R1 ) 

( R1 ) 

FI ( 

>, OBJECT- 

F1 ? 

R2 ( 

) R2 ( 

F2 J 

If2 ' 


The SOURCE keyword parameter is used if the 
source program is located in a source library. You 
must supply the same name given to the source 
program when it was stored in the library by the 
Library Maintenance program. The UNIT para¬ 
meter must be used with the SOURCE parameter 
to identify the disk location of the source program 
to be compiled. 


If the SOURCE keyword parameter is not used, 
the source program is assumed to be on cards 
following the RUN statement in the job stream. 

The OBJECT keyword parameter tells the system 
where the disk which will contain the object 
program is located. If the source program is on 
cards, the OBJECT keyword parameter is the only 
parameter which can be specified. If the OBJECT 
keyword parameter is omitted in either case, the 
object program is placed on the same disk pack as 
the compiler. 


1. Compile a source program from a source 
library and store the object program in an ob¬ 
ject library, or 

2. Compile a source program from cards and store 
the object in an object library. 


For example, for RPG II programs, the name assigned 
to the object program in the object library is the name 
you assigned in the Program Identification (columns 
75-80) in the RPG II Control Card. If you did not 
assign a name in these columns, RPGOBJ is assumed. 
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Figure 21. File Statement and Use of the LOCATION Parameter 
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Sample Statements 



This sample job stream tells the system that the 
source program named SALES is located on a 
fixed disk on drive one (FI). The OBJECT-R1 
keyword parameter tells the system to place the 
object program on a removable disk on drive one 
(R1). 
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This sample job stream compiles a source program 
on cards and stores it in an object library on R1. 

If the OBJECT parameter was not coded, the pro¬ 
gram would be compiled and placed into the 
same object library as the compiler (FI). 


LOADING PROGRAMS IN A DPF ENVIRON¬ 
MENT 

A program can be loaded into either program level 
first. You tell the supervisor which system input 
device contains the job streams for the programs 
by selecting the device on the Dual Program Control 
Switch. (Refer to the IBM System/3 Disk System 
Operator's Guide, GC21-7508 for further operating 
procedures.) When preparing your job streams, 
you should be aware of the following OCL consider¬ 
ations: 


OCL CONSIDERATIONS FOR LOADING PROGRAMS IN A DPF ENVIRONMENT 


DATE statement 


LOG statement 


The DATE statement you use as an IPL statement to set the system date must be 
supplied with the first program loaded in one program level. The DATE statement 
must precede the set of statements for the first program. In the device associated 
with the other program level, a DATE statement must not precede the sets of 
statements for the programs being run in that level. 

A DATE statement that temporarily changes the system date can be used within 
the set of OCL statements for programs in either program level. This DATE 
statement applies only to the program for which it is used. 

LOG statements can be placed anywhere among the statements in either job 
stream. There are, however, certain restrictions on their use. 

- Only LOG statements for program level 1 can tell the system to use a dif¬ 
ferent logging device. Only ON or OFF can be specified in program level 2. 
The device used for level 1 is also used for level 2. 






OCL CONSIDERATIONS FOR LOADING PROGRAMS IN A DPF ENVIRONMENT (continued) 


— LOG must be on for both program levels before logging can occur. If a 
LOG statement for either program level stops the logging function, logging 
is stopped for both levels. The program level that turned the logging device 
off must turn it back on before logging can resume. If both levels specify 
OFF, then both program levels must turn the logging device back on before 
logging can resume. 

— When the printer is the logging device, OCL statements and message codes 
are not printed if the program in either level uses the printer as an output 
device. 

The following example shows sample LOG statements in a job stream: 



Note: The first LOG statement indicates that the printer is used as the logging 
device while program PROG1 is being run. OCL statements and error messages 
are not printed for program PROG2 because of the second LOG statement. The 
third LOG statement causes the logging device to be used again. 

NOHALT statement The NOHALT statement is ignored for program level 2. The program in this 

level always stops after each job. 

HALT statement The HALT statement is ignored by program level 2. 

IMAGE statement The IMAGE statement is invalid and the job cannot be run, if the other level has 

the printer allocated to it. 


FORMS statement 


The FORMS statement is invalid and the job cannot be run, if the other level has 
the printer allocated to it. 


LOAD statement 


The LOAD* statement cannot be used in program level 2. 


LOCKOUT statement The LOCKOUT statement is used only on a DPF system. It is used to suspend the 

other program level to allow faster job initiation in the program level in which it is 
entered. 

PARTITION statement The PARTITION statement is used only on a DPF system. It is used to guarantee 

a minimum size to level 2 for a subsequent program in that level. 
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OCL CONSIDERATIONS FOR LOADING PROGRAMS IN A DPF ENVIRONMENT (continued) 



Supervisor 


Program Level 1 


Unused Area 

Program Level 2 

4 

(a minimum of 5K bytes 

i 

of storage is reserved) 

i 

i 

> 


Without a PARTITION Statement 

If level 1 is not using the storage and a 
program is loaded into level 2, it is assigned 
the number of bytes requested by program 
attributes or a minimum of 5K bytes for systems 
with 16K bytes or more of main storage. When 
the program in level 2 comes to end of job, the 
storage for level 2 is no longer reserved and 
level 1 can use it. 


With a PARTITION Statement 

If a PARTITION statement is used, the 
assigned storage can only be used by the 
program in level 2. It is reserved. Even 
when the program in level 2 comes to 
end of job that storage is reserved for 
future programs in level 2. 


If you do not use a PARTITION statement and, therefore, do not indicate the 
minimum size of program level 2, the system automatically assigns, during 
execution, the storage needed to level 2 or a minimum of 5K bytes for systems 
with 16K bytes or more of main storage. You cannot submit a PARTITION 
statement in program level 2 or when program level 2 is processing. In a 
procedure the PARTITION statement must follow the LOAD statement and 
precede the RUN statement. 

The format of the PARTITION statement is: 

// PARTITION size 

You must state the minimum number of bytes of storage you want to save for 
program level 2. The number must be equal to or greater than 5120. The 
amount of storage you specify is rounded to the next highest 256 byte increment 
by the supervisor, if it is not a multiple of 256. 
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DPF Considerations for 12K Systems 

All programs require 5K bytes of storage for initia¬ 
tion and termination even though a program may 
occupy less than 5K. System programs use this 
storage for performing system functions just prior 
to loading the user's object program (initiation) and 
again immediately following the end of object pro¬ 
gram execution (termination). 

This 5K requirement also affects DPF. For inde¬ 
pendent initiation and termination of a program on a 
DPF system, at least 5K bytes of storage must be avail¬ 
able for each program level, regardless of the size of 
the program to be executed. If a program needs less 
than 5K while another program requires the remain¬ 
ing storage which is 5K or larger, the smaller pro¬ 
gram must be initiated first so that the storage re¬ 
quired by the system for initiation will be available. 
The system can then use all the storage not re¬ 
quired by the smaller program for the larger program. 
However, the smaller program must wait for termin¬ 
ation of the larger program, so that 5K is available 
for the smaller program's termination. 

In a 12K DPF system only limited independent 
initiation and termination is allowed. With a 4K 
minimum size requirement for the supervisor only 
8K is available for user programs. Independent pro¬ 
gram initiation and termination for each program 
is possible if each program being run occupies 3K 
or less of storage. The remaining 2K of storage is 
used alternately by either program to satisfy the 
5K system requirement. If one program needs more 
than 3K, the smaller program must be initiated first 
and can have a maximum executing size of 3K. The 
larger program is then initiated and can occupy the 
remaining storage. The larger program level must 
be terminated before the smaller program level. 


Sample Job Streams 

Suppose you had four jobs to be run requiring the 
I/O shown in Figure 22. Jobs 1 and 2 and Jobs 
3 and 4 can be run together, because they do not 
require the same I/O devices. If Job 2 finishes 
before Job 1, you could run Job 4 because Jobs 1 
and 4 do not require the same devices. If, on the 
other hand, Job 1 finishes first. Job 3 could not 
be run with Job 2, because both jobs require the 
printer for output. 

Figure 23 shows the job streams required to load 
the four jobs. Assume the system has the mini¬ 
mum system configuration plus the 5471 Printer- 
Keyboard and dual drives. The Dual Program 
Switch indicates from which device OCL statements 
are read. MFCU refers to hopper 1. At system 
generation time P-KB was assigned to the 5471 
Printer-keyboard. 



JOB1 

JOB3 


An inquiry 

A stock status report 


program that: 

that: 

Program 

• Reads printer- 

• Reads disk. 

Level 1 

keyboard. 

• Prints. 


• Reads disk. 



• Writes printer- 



keyboard. 



JOB2 

JOB4 


An inventory 

A detail punching 


updating program 
that: 

job that: 

Program 

• Reads cards. 

• Reads cards. 

Level 2 

• Reads disk. 

• Punches cards. 


• Updates disk. 



• Prints. 



Figure 22. Job Scheduling for DPF 
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RESTARTING A CHECKPOINTED PROGRAM 

Checkpoint is a means of recording the status of a 
problem program at desired intervals. Restart is a 
means of resuming the execution of the program 
from the last checkpoint rather than from the begin¬ 
ning, if processing is terminated for any reason (with 
the exception of a controlled cancel) before the 
normal end of job. For example, a power failure may 
occur and cause an interruption. 

Programming Considerations 

• Checkpoint/Restart enables the user to restart a 
checkpointed program from the last checkpoint 
taken provided no intervening program executions 
have taken place. 

• Sufficient disk space is allocated by Library 
Maintenance on a checkpoint system pack (5444) 
at System Generation or Library Maintenance 
time to allow one active checkpoint. On a system 
with Checkpoint and Inquiry, the disk space will 
be used by both functions. The checkpoint pro¬ 
gram cannot be an inquiry evoking program since 
the disk space is used by both facilities. 

• Checkpoint requests are accepted only in program 
level 1. Checkpointed programs must be restarted 
in program level 1. If program level 2 is used to 
execute a checkpointed program, the checkpoint 
requests are ignored. 


Restart Procedure 

To restart the interrupted job at the last checkpoint 
submit the following OCL statements: 

// LOAD $$RSTR, unit 
// RUN 

The unit in this example is a pack with module 
$$RSTR. If an I PL occurs it must be from the pack 
with the active checkpoint. 

If an intervening program is run, an IPL must occur 
and be from a pack other than the pack that contains 
the active checkpoint. Programs executed under con¬ 
trol of the new IPL system must not access disk vol¬ 
umes used in the active checkpointed program or 
modify the object library where the checkpointed 
program resides. 

Other OCL statements that may be required are the 
PARTITION and LOG statements. 


OCL CONSIDERATIONS FOR USING CHECKPOINT/RESTART 


PARTITION statement A PARTITION statement may be required at restart to guarantee 

the required minimum level 2 size. See Loading Programs in a 
DPF Environment for further information on the PARTITION 
statement. 

— A halt will occur if restart is attempted without sufficient 
space in program level 1. An immediate cancel is taken. 

— Checkpoints can only be taken in program level 1. To 
restart a checkpointed program, program level 1 must be 
used. If level 2 is used to execute a checkpointed program, 
the checkpoint requests are ignored. 

— Restart requires 5K of storage, therefore level 2 must be 
such that level 1 has 5K. 

LOG statement A LOG statement may be required at restart to reestablish the 

logging device. See LOG Statement under Statement Descrip¬ 
tions and Loading Programs in a DPF Environment for further 
information on the LOG statement. 
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STATEMENT EXAMPLES 

This section shows an example that illustrates 
some of the uses of the OCL statements. The 
example consists of a series of jobs. The jobs in¬ 
volve three files: customer, inventory, and transac¬ 
tion. The customer file contains such information 
as customer names and addresses, total amounts 
of charges over a period, and total amounts of 
payments over the same period. The inventory 
file contains such information as item numbers 
and descriptions, prices of the items, and the 
numbers of items in stock. The transaction file 
contains such information as orders for items, re¬ 
fund orders for items returned, and customer 
payments. The transaction file is used to update 
the inventory and customer files. 

Example 

The OCL statements for the jobs are shown in 
Figure 24. Sets of statements in the figure are 
numbered. The explanations corresponding to 
those numbers are given in the following section. 

Explanation 

1. The DATE statement supplies the system date, 
10/20/71. It must be read by the system before 
the first LOAD or CALL statement after initial 
program load. 


2. Two programs are being compiled: one that 
transfers the customer file from cards to disk; 
and one that transfers the inventory file from 
cards to disk. The OCL statements for the 
RPG II Compiler are in a procedure called RPG. 
A CALL statement, therefore, is used to instruct 
the system to read the procedure each time the 
compiler is to be run. The procedure is located 
on the fixed disk on drive one. 

The RPG 11 source programs following each set 
of CALL and RUN statements are input to the 
compiler. Like all input, each source program 
must be followed by a /* card. However, to 
be safe, /& statements were used before each 
LOAD and CALL statement in case the /* cards 
had not been placed after the source programs. 

3. In the next two jobs, the object programs just 
compiled will be run. The comment and PAUSE 
statements are to remind the operator to place 
the object- program cards after the correspond¬ 
ing sets of OCL statements. 

4. The system stops, temporarily, after each of the 
preceding compilations, giving the operator 
time to ensure that the compilations were 
successful. However, there is no need for the 
system to stop after the next few jobs. A 
NOHALT statement, therefore, is given at 

this point. 



© i 
© ( 


Figure 24 (Part 1 of 4). OCL Statement Example 
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5. The two object programs previously compiled The cards containing the records to be trans- 

are being run to transfer the customer and in- ferred to disk are being read from the same 

ventory files, respectively, to disk. device as the OCL statements. In each case, the 

cards must immediately follow the program 
In each case, a disk file is being created. Both that reads them. If the programs had been 

files are permanent. The name that will iden- loaded from disk, the cards would have fol- 

tify the customer file on disk is CUST; the lowed the RUN statement in each case, 

inventory-file name is INV. The date for both 
files will be 10/20/71. 



Figure 24 (Part 2 of 4). OCL Statement Example 



Figure 24 (Part 3 of 4). OCL Statement Example 
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6. A program that transfers a transaction file, 
TRANS, from cards to disk is being compiled. 
Because the resulting object-program cards are 
to be placed with the next set of OCL state¬ 
ments, comment and PAUSE statements are 
used to remind the operator. 

7. The transaction file is first transferred from 
cards to disk, and then sorted on disk by the 
Disk Sort program. A HALT statement pre¬ 
cedes the sort job so that the system will stop 
after the sort job. This gives the operator a 
chance to check any diagnostic messages to en¬ 
sure that the sort was successful. The HALT 
statement remains in effect for the remaining 
jobs. 

The INPUT and OUTPUT files are the same. 
The transaction file is read, sorted, and then 
written back on the same area of disk. 


The sort specification cards following the 
RUN statement are input to the Disk Sort 
program. Like all input, the last card must be 
a /* card. 

8. The program that updates the inventory file 
with information from the transaction file is 
compiled. Comment and PAUSE statements 
again remind the operator to include the ob¬ 
ject-program cards with the next set of OCL 
statements. 

9. The program just compiled is run to update 
the inventory file. This program can also print 
the transaction-file records. The printed out¬ 
put file, however, is conditioned by external 
indicator U1. Because the SWITCH state¬ 
ment sets U1 on, the transaction records will 
be printed. If the SWITCH statement had not 
been used, the indicator would have remained 
off and the records would not have been printed 
(external indicators are all initialized off at 

IPL time). 


© 




Figure 24 (Part 4 of 4). OCL Statement Example 
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INTRODUCTION TO SYSTEM UTILITY PROGRAMS 


The Disk System includes a group of disk resident utility programs. These pro¬ 
grams do a variety of jobs, from preparing disks and tapes for use to maintaining 
the system libraries. The utility programs are: 

• Tape Initialization 

• Tape Error Summary Program 

• Disk Initialization 

• Alternate Track Assignment 

• Alternate Track Rebuild 

• File and Volume Label Display 

• File Delete 

• Disk Copy/Dump 

• Dump/Restore 

• Library Maintenance 

• 5445 Data Interchange Utility 


The information for every program is divided into five sections: 

• Control statement summary 

• Parameter summary 

• Parameter descriptions 

• OCL (operation control language) considerations 

• Examples 

TO WRITE UTILITY CONTROL STATEMENTS 

To write utility control statements (see Control Statements), use the sections in the 

following way: 

1. Look at the Control Statement Summary to determine which control statements 
and parameters apply to the program uses you are interested in. (The program 
uses are stated in the text preceding the Control Statement Summary.) 

2. If you need information about the contents or meanings of particular parameters, 
look at the Parameter Summary. 

3. If you need more detailed information about parameters, read the Parameter 
Descriptions following the Parameter Summary. 

4. If you need examples of specific jobs, look at the Example section. All examples 
show the OCL statements and utility programs for specific jobs. 

5. To find information concerning the use of the utility programs, refer to 
OCL Considerations for the necessary OCL statements. 
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Control Statements 

All of the programs require utility control statements, which you must supply. 

These statements give the program information concerning the output you want 
the program to produce or the way in which you want the program to perform 
its function. The programs read these statements from the system input device. 

They must be the first input read by the programs. 

Every control statement is made up of an identifier and parameters. The identifier 
is a word that identifies the control statement. It is always the first word of the 
statement. Parameters are information you are supplying to the program. Every 
parameter consists of a keyword, which identifies the parameter, followed by the 
information you are supplying. 

Coding Rules 

The rules for constructing control statements are as follows: 

1. Statement identifier. // followed by a blank should precede the statement identi¬ 
fier. Do not use blanks within the identifier. 

2. Blanks. Use one or more blanks between the identifier and the first parameter. 

Do not use them anywhere else in the statement. 

3. Statement parameters. Parameters can be in any order. Use a comma to separate 
one parameter from another. Use a hyphen (-) within each parameter to separate 
the keyword from the information you supply. Do not use blanks within or be¬ 
tween parameters. 

4. Statement parameters containing a list of data after the keyword. Use apostrophes 
(') to enclose the items in the list. Use a comma to separate one item from another. 
For example: UNIT-'R1,R2' (R1 and R2 are the items in the list). 

5. Statement length. All control statements except Library Maintenance state¬ 
ments must not exceed 96 characters. The following Library Maintenance 
statements can be continued on another statement. (See Continuation under 
Coding Rules in Part I of this manual.) 

//ALLOCATE 

// COPY (except for file-to-library) 

//DELETE 

// MODIFY (not REMOVE, REPLACE, or INSERT statements) 

// RENAME 

The following is an example of a control statement: 

// COPY FROM-F1,LIBRARY-O,NAME-SYSTEM, TO-R1 

The statement identifier is COPY. The parameter keywords are FROM, LIBRARY, 
NAME, and TO. The information you supply is FI, 0, SYSTEM, and R1. 

End Control Statement 

The END statement is a special control statement that indicates the end of control 
statements. It consists of // END starting in position 1 and must always be the last 
control statement for the programs. 



SPECIAL MEANING OF CAPITAL LETTERS, NUMBERS, AND SPECIAL 
CHARACTERS 

Capitalized words and letters, numbers, and special characters have special meanings 
in OCL and utility control statement descriptions. 

In utility control statements, capitalized words and letters must be written as they 
appear in the statement description. Sometimes numbers appear with the capitalized 
information. These numbers must also be written as shown. 

Words or letters that are not capitalized mean you must use a value that applies to 
the job you are doing. The values that can be used are listed in the parameter sum¬ 
maries for the control statements. 

Braces ( { } ) sometimes appear in parameters shown in control statement sum¬ 
maries and parameter summaries. They are not part of the parameters. They simply 
indicate that you must choose one of several values to complete the parameter. For 
example, RETAIN- j p | means you can use either RETAIN-T or RETAIN-P. 
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TAPE INITIALIZATION PROGRAM~$TINIT 


The Tape Initialization Program prepares tapes for use. It writes IBM standard 
volume labels on tape in order for tape data management to perform IBM standard 
label processing. The program is available on either card or disk. 

The Tape Initialization Program performs these functions at your request: 

• CHECK labeled tapes for a volume label and an unexpired file before writing 
a new volume label. 

• CLEAR labeled or unlabeled tapes by bypassing CHECK and unconditionally 
initializing the tape. 

• DISPLAY the volume and header labels. 

All tapes must be initialized before use. Tapes that have been initialized need not 
be reinitialized unless you want to write a new volume label or use a tape that 
contains a permanent file for output. This program can either initialize (CLEAR 
or CHECK) or DISPLAY one tape per unit during the same program run. 
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CONTROL STATEMENT SUMMARY 


Use 

Check for an expired 
file and a label, then 
write a new label. 


Write volume label 
without checking 
for old label. 


Display volume 
label. 


Control Statement 


// VOL UNIT- 



,REEL- 


jNL I 
( xxxxxx ) 


TYPE-CHECK, ASCII- 


(YES 
( NO 




DENSITY- 
// END 


1600 
j 800 I 
( 556 \ 
200 


,ID*yy...yy 



//VOL UNIT- < , REEL- | NL f ,TYPE-CLEAR,ASCII- , 

) T3 ( ( xxxxxx ) (NO 1 


DENSITY- 
// END 


1600 
800 > 
556 \ 
200 


,ID-yy...yy 


// VOL UNIT- 



,TYPE-DISPLAY,DENSITY 


800 ) 
556 r 
200 ) 


// END 

Notes: 1. If density is not specified, the default for seven track tape units is 800 bpi, the default for nine track tape units is 

1600 bpi. 

2. The DENSITY parameter on display volume label is valid only for seven track tape units. 

3. Valid density for seven track tape units is 200, 556, and 800 bpi. Valid density for nine track tape units is 800 
bpi (if dual density feature is installed), and 1600 bpi. 


PARAMETERS 

TYPE-CHECK 

Check to see if the file has expired, then write a new label. Do not use this on blank tapes because 
the program attempts to read a blank tape causing tape runaway. 

TYPE-CLEAR 

Write a new volume label without checking for an expired file. 

TYPE-DISPLAY 

Print the contents of the volume label and the header labels. 

UNIT-code 

Specifies which tape drive contains the tape to be initialized. Possible codes are: T1, T2, T3, 
and T4. A separate VOL statement is needed for each tape unit that contains a tape to be 
initialized. 

REEL-NL 

Specifies that an unlabeled tape is to be generated. 

REEL-xxxxxx 

Specifies the volume serial number that the Tape Initialization program writes on tape. Must be 
alphabetic A-Z, @, #, $, or numeric 0-9. 

ASCII-YES 

The tape is written in ASCII code. This is invalid for seven track tape. 

ASCII-NO 

The tape is written in EBCDIC code. If the ASCII parameter is omitted, NO is assumed. 
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PARAMETERS (continued) 


DENSITY-200 

The tape is written at a density of 200 bits per inch. The file written on this tape unit must be 
written at this density. 

DENSITY-556 

The tape is written at a density of 556 bits per inch. The file written on this tape unit must be 
written at this density. 

DENSITY-800 

The tape is written at a density of 800 bits per inch. The file written on this tape must be 
written at this density. 

DENSITY-1600 

The tape is written at a density of 1600 bits per inch. The file written on this tape must be 
written at this density. 

ID-xxxxxxxxxx 

Provides an additional identification field. This field is not processed by the system. A maximum 
of ten characters can be used if ASCII-NO is specified. If ASCII-YES is specified, 14 characters 
can be used. This is an optional parameter. 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the Tape Initialization program. 

// LOAD $TINIT,CODE 
// RUN 

The code you supply depends on the location of the 
disk containing the Tape Initialization program. The 
codes are as follows: 


Code Meaning 

R1 Removable disk on 5444 drive 

one. 

FI Fixed disk on 5444 drive one. 

R2 Removable disk on 5444 drive 

two. 

F2 Fixed disk on 5444 drive two. 


MESSAGES FOR TAPE INITIALIZATION 


Message 

Meaning 

INITIALIZATION ON 
xx COMPLETE 

This message is printed when initialization of a tape is complete, 
xx indicates the unit (T1, T2, T3, or T4) on which the 
initialization is complete. 
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PRINTOUT OF VOLUME LABEL 

The following sample jobs shows the format of data 
printed by the Tape Initialization Program from a 
nine track tape unit and from a seven track tape 
unit. 


// LOAD $TINITtP1 
// HALT 


// RUN 

ft VOL UNIT~T1,TYPE-DISPLAY 
ft VOL UNIT-T2,TYPE-DISPLAY 
// END 





*** OISPLAY 

ON 

UNIT Ti *** 


LABEL 

SERIAL 

OWNER CODE 





VOL I 

T1T1T1 






LABEL 

FILE \ 

DENT IF I ER 

FILE SERIAL 

VOL SEQ NO 

CREATE DATE 

HDRI 

FILE1 


TIT IT ! 


OOOi 

72251 

LABEL 

REC FORM 

BLK LENG 

REC LENG 

RECORDING TECH 

PRTR CNTRL B 

HDR2 

F 

00018 

00018 


e 



*** DISPLAY ON UNIT T/. *** 

LABEL SERIAL OWNER CODE 
VOLT T2T2T2 


LABEL FILE IDENTIFIER FILE SERIAL VOL SEQ NO CREATE DATE 

HDRi FILE2 T2T2T2 0001 72251 


LABEL REC FORM BLK LENG REC LENG RECORDING TECH PRTR CNTRL BLK 
HDR2 F 00180 00018 T I 


ff LOAD $TINIT«F1 
ft RUN 

ft VOL UNIT-Tl,TYPE-DISPLAY 
ff VOL UNIT-T2tTYPE-DISPLAY 
(/ VOL UN IT-T3* TYPE-01SPLAY 
ft VOL UNIT-T4,TYPE-DISPLAY 
ft END 


*** DISPLAY ON UNIT T1 *** 

LABEL SERIAL OWNER CODE 
VOLl XRAY03 


LABEL 

FILE IDENTIFIER 

FILE SERIAL 

VOL SEC NO 

HDRI 

TAPEOUT 


XRAY03 


0001 

LABEL 

REC FORM 

BLK LENG 

REC LENG 

RECORDING TECH 

HDR2 

F 

01260 

00084 






*** DISPLAY 

ON 

UNIT T2 *** 

LABEL 

SERIAL 

OWNER CODE 




V0L1 

US6R14 





LABEL 

FILE I! 

DENT!FIER 

FILE SERIAL 

VOL SEC NO 

HDRI 

TAPOUT 


USER14 


0001 

LABEL 

REC FORM 

BLK LENG 

REC LENG 

RECORDING TECH 

HDR2 

F 

00080 

00080 




CREATE DATE 
72082 

PRTR CNTRL BLK 


CREATE DATE 
72067 

PRTR CNTRL BLK 


EXPIRE DATE 
72251 

A TTR 


EXPIRE DATE 
72251 

ATTR 


EXPIRE DATE 
99999 

A~TR 


EXPIRE DATE 
72087 

A^TR 
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*** DISPLAY ON UNIT 13 

LABEL SERIAL OWNER CODE 
VOL1 XRAY04 


LABEL 

HDRi 

FILE IDENTIFIER 
TAPEOUT 

FILE SERIAL 
XRAY04 

VOL SEQ 
0001 

NO CREATE DATE 

72083 

EXPIRE DATE 
99999 

LABEL 

HDR2 

REC FORM 

F 

BLK LENG 
01260 

REC LENG RECORDING TECH 

00084 

PRTR CNTRL BLK 

ATTR 

B 


LABEL 

SERIAL 

*♦* DISPLAY ON UNIT T4 *** 

OWNER CODE 

VOL 1 

TEST4 

ASCII TAPE LABEL 


MEANING OF VOLUME LABEL INFORMATION 

Display of Volume Label 


Heading 

Meaning 

LABEL 

VOL1 indicates this is a volume label. 

SERIAL 

The volume serial number (from the REEL parameter). 

OWNER CODE 

Additional identification (from the ID parameter). 

Display of Header 1 Label 


Heading 

Meaning 

LABEL 

HDRI indicates this is a header 1 label. 

FILE IDENTIFIER 

The filename of the file on tape. This is the name from the LABEL parameter of the OCL FILE 
statement when the file was created. 

FILE SERIAL 

The serial number of the tape volume. This is the same as the SERIAL field in the volume label. 

VOL SEQ NO 

The sequence number of this volume in a multivolume file. 
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MEANING OF VOLUME LABEL INFORMATION (continued) 


Display of Header 1 Label (continued) 

Heading 

Meaning 

CREATE DATE 

The date this file was created. This is a Julian date. The format is yyddd where yy is the last two 
digits of the year and ddd is the day in the year. Example: 72094 = the 94th day of 1972, or 

March 3,1972. 

EXPIRE DATE 

Display of Header 2 Label 

The date this file expires. This Julian date is the creation date plus the number of days specified 
by the RETAIN parameter on the OCL FILE statement. 

Heading 

Meaning 

LABEL 

HDR2 indicates this is a header 2 label. 

REC FORM 

The record format of this file. (From the RECFM parameter on the OCL FILE statement when this 
file was created.) The formats are: 

F — Fixed length 

V — Variable length 

U — Undefined length 

BLK LENG 

Block length. (From the BLKL parameter on the OCL FILE statement when this file was created.) 

REC LENG 

Record length. (From the RECL parameter on the OCL FILE statement when this file was created.) 

RECORDING TECH 

T — Odd parity with translation 

C — Odd parity with conversion 

E — Even parity without translation 

ET — Even parity with translation 

blank — Odd parity without translation or conversion 

PRTR CNTRL 

Printer control character. This field will be blank on tapes created on System/3. For tapes 
created on other systems, the characters are: 

A — ASCII control characters 

M — Machine control characters 

blank — No control characters 

BLK ATTR 

Block attributes: 

B — Blocked records 

S — Spanned records 

R — Blocked and spanned records 

blank — Neither blocked nor spanned 

Note: Spanned records cannot be created on System/3. 
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TAPE ERROR SUMMARY PROGRAM—$TVES 


The IBM System/3 Disk System keeps track of errors that occur on the tape drives. 
This error information is stored in the Customer Engineer tracks on 5444 fixed 
drive one. You should run the Tape Error Summary Program periodically to provide 
a summary, by volume and by unit, of temporary read and write errors. 

There are no control statements necessary for this program. After being loaded 
from the program or system pack, the Tape Error Summary Program reads the data 
from the disk and sorts it by volume and unit. When all the data is read or the 
available main storage is filled, the error data is printed. If no tape errors are 
recorded, the message THERE ARE NO VALID TAPE ERRORS LOGGED is 
printed. 


ERROR LOGGING FORMAT 


SUMMARY 

MAGNETIC 

TAPE 

ERROR STATISTICS BY VOLUME DATE 03/27/72 

© 

© 

© 

© 

© 

VOLUME 

SIO 

TEMP 

TEMP 

WRITE 

SERIAL 

COUNT 

READ 

WRITE 

SKIP 

T1 

06512 

0000 

0028 

0028 

TAPE1 

00016 

0000 

0001 

0001 

TAPE3 

00021 

0000 

0001 

0001 


SUMMARY 

MAGNETIC 

TAPE 

ERROR STATISTICS 

BY TAPE UNIT DATE 03/27/72 


© 

© 

© 

© 

© 

TAPE 

SIO 

TEMP 

TEMP 

WRITE 

DIAG 

UNIT 

COUNT 

READ 

WRITE 

SKIP 

TRACK 

T1 

06528 

0000 

0029 

0029 

0000 

T4 

00021 

0000 

0001 

0001 

0000 



For unlabeled tapes and the first volume of a multivolume file that has more than two volumes per unit, 
„„„ is printed as the volume serial. For tapes with non-standard labels, ****** is printed as the volume 
label. 


The number of tape operations performed. (SIO means Start I/O.) 
3 ) Temporary read errors. 

Temporary write errors, 
j } Write skips caused by temporary write errors. 


Diagnostic track errors. This is used by IBM Customer Engineers. 


Tape Error Summary Program—$TVES 95 





OCL CONSIDE RATIONS 

The following OCL statements are needed to load 
the Tape Error Summary Program. 

// LOAD $TVES,code 
//RUN 

The code is the disk unit that contains the program 
(FI, R1, F2, or R2). 
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DISK INITIALIZATION PROGRAM—$INIT 


All disks must be initialized before use. Disks that have been initialized need not 
be re-initialized unless you want to erase their contents and rename them. 

The Disk Initialization program prepares disks for use. It does this by: 

• Writing track and sector addresses on the disk. 

• Checking for defective tracks, a process called surface analysis. 

• Assigning alternate tracks to any defective tracks found. 

• Writing a name on each disk to identify the disk. 

• Formatting the volume table of contents. 

The process is called initialization. The program can initialize up to five disks 
during the same program run. 

There are three types of initialization: primary, secondary, and clear. Primary is 
used to initialize any disk to disk drive capacity. Secondary is used only when 
using the 5444 disk and only when the drive capacity of your system is increased 
and you have programs and data on your disks that you want to keep. Clear is 
used to unconditionally initialize a disk. 

CAUTION 

Clear will destroy any files or libraries that 
were previously on disk. 

The control statements you supply for the Disk Initialization program depend 
on the type of initialization and the number of disks you are initializing. 
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PARAMETER SUMMARY 



UIN (Input Definition) Statement 

TYPE-PRIMARY 

Primary initialization. Initialize the disks to the capacity of the drives on which they 
are mounted. Tracks already initialized are re-initialized. The program will not 
initialize disks containing libraries, temporary data files, or permanent data files. 

TYPE-SECONDARY 

Secondary initialization (5444 disk only). Applies only to disks that were 
initialized on drives of less capacity than the drives you are now using. It means 
initialize the uninitialized portions of the disks to the capacity of the drives on 
which the disks are mounted. Tracks already initialized are not disturbed. 

TYPE-CLEAR 

Clear initialization. Initialize the disks to the capacity of the drives on which they 
are mounted. Tracks already initialized are re-initialized. Active files and library 
checking is bypassed and^ny data on the tracks is destroyed. 

UNIT-code 

Disk location (one disk). ~ 

Possible 

codes: 

UNIT-'code,code' 

Disk location (two disks). 

R1,FI, 

R2, F2 

UNIT-'code ,code ,code' 

UN IT-'code,code,code,code' 

Disk location (three disks). 

Disk location (four disks). 

D1, D2 

UNIT-'code ; code,code,code, 



code' 

Disk location (five disks). 


VERIFY-number 

Do surface analysis the number of times indicated (number can be 1-255). VERIFY-1 
is assumed if you omit the parameter. 

ERASE-YES 

ERASE-NO 

Retest defective tracks. “] 

Do not retest defective tracks. J 

Primary initialization only. ERASE-NO is 
assumed if you omit the parameter. 

CAP-HALF (?) 

Initialize a disk to half capacity even if on a full capacity drive (5444 disk only). 

CAP-FULL 0 

Initialize a disk to full capacity (5444 disk only). 

VOL (Volume) Statement 

PACK-name 

Disk name. Can contain any of the standard System/3 characters except apostrophes, 
leading or embedded blanks, and embedded commas^. Its length must not exceed 
six characters. 

ID-characters 

Additional identification. Can contain any of the standard System/3 characters 
except apostrophes, leading or embedded blanks, and embedded commasQ). Its 
length must not exceed ten characters. If you omit this parameter no additional 
identification is written on the disk. 

NAME360-characters 

Additional identification for 5445 disk. The name will be placed in the 

System/360 format 1 DSCB. Can contain any of the standard System/3 
characters except apostrophes, leading or embedded blanks, and embedded 
commas . Its length must not exceed 44 characters. If you omit this 

parameter the program defaults to SYSTEM/3.DATA. 

^^The CAP keyword forces ERASE-YES. Pack is initialized to capacity of the drive if this keyword is omitted. 

^^This is due to their delimiter function. 
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PARAMETER DESCRIPTIONS 


Clear Initialization 


TYPE Parameter (UIN) 

The TYPE parameter indicates the type of initializa¬ 
tion you want the program to do: primary, secon¬ 
dary, or clear. The type of initialization and the ca¬ 
pacity of the disk drives on which the disks are 
mounted determine which disk tracks will be 
initialized. 

Disk Drive Capacity 

Disk drives of different data-storage capacities are 
available for the System/3 Model 10 Disk System. 
The difference is the number of tracks the drives can 
use: the larger the drive capacity, the more tracks 
the drive can use. However, you must initialize the 
disk tracks before using them. 

Primary initialization 

Primary initialization applies to new disks, or disks 
you have used but want to initialize again. The pro¬ 
gram initializes all tracks corresponding to the 
capacity of the drives on which the disks are 
mounted. Tracks that were previously initialized 
are initialized again. Any data on the tracks is 
destroyed. 

Note: A 5445 disk with an invalid System/3 label must 

be initialized using the clear initialization. 

You can use primary initialization on a disk as often 
as you want. However, the program will not 
initialize disks containing libraries, temporary 
data files, or permanent data files. You must de¬ 
lete the files using File Delete and the libraries 
using the allocate function of Library Maintenance. 

Secondary Initialization (5444 Disk Only) 

Secondary initialization applies to disks that were 
initialized on drives of less capacity than the drives 
you are now using. When you increase the capacity 
of your drives, more tracks on your disks be¬ 
come available for use. You must initialize the 
additional tracks. Use secondary initialization 
if you do not want information destroyed on 
tracks already in use. The program initializes the 
additional tracks only. Tracks already in use are 
not disturbed. 

The program will not do secondary initialization 
on new disks or disks that have already been 
initialized to the capacity of the drives on which 
they are mounted. 


Clear initialization applies to new disks or disks previously 
used that require reinitialization due to invalid pack labels 
or some other unrecoverable disk error. All tracks corres¬ 
ponding to the capacity of the drives on which the disks 
are mounted are initialized. Tracks that were previously 
initialized are re-initialized. 

Warning: All libraries, temporary data files, or 
permanent data files are completely erased. 

UNIT Parameter (UIN) 

The UNIT parameter (UNIT-code) tells the location 
of the disks you want to initialize. The program 
can initialize up to five disks during one program 
run. 

The form of the UNIT parameter depends on the 
number of disks you are initializing: 

1. For one disk, use UNIT-code. 

2. For two disks, use UN IT-'code,code'. 

3. For three disks, use UNIT-'code,code,code'. 

4. For four disks, use UNIT-'code,code,code,code'. 

5. For five disks, use UNIT-'code,code,code,code, 
code'. 

The codes indicate the locations of the disks: 


Code 

Meaning 

R1 

Removable disk on 
5444 drive one 

FI 

Fixed disk on 5444 
drive one 

R2 

Removable disk on 
5444 drive two 

F2 

Fixed disk on 5444 

drive two 

D1 

Removable disk on 

5445 drive one 

D2 

Removable disk on 

5445 drive two 
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For primary initialization, the order of codes must 
correspond to the order of VOL control state¬ 
ments. If, for example, you had used the parameter 
UNIT-'R1,R2', the first VOL statement applies 
to the removable disk on drive one and the second 
VOL statement to the removable disk on drive 
two. (No VOL statements are required for second¬ 
ary initialization. The disk is already named.) 

You cannot initialize the pack from which you 
loaded the Disk Initialization program or the 
system pack. 

VERIFY Parameter (UIN) 

The VERIFY parameter (VERIFY-number) con¬ 
cerns surface analysis. It enables you to indicate 
the number of times you want the program to do 
surface analysis before judging whether or not 
tracks are defective. The number can be from 
1 to 255. The greater the number specified in the 
VERIFY parameter the longer it takes to initialize 
the disk. 

On a 5444, the time for initializing using VERIFY-1 
is approximately two and one-half minutes. Each 
additional verify takes two minutes and ten seconds. 
On the 5445, the time for initializing using VERIFY-1 
is approximately 15 minutes. Each additional verify 
on the 5445 takes seven minutes. 


Surface Analysis 

Surface analysis is a procedure for testing the con¬ 
dition of tracks. It consists of writing test data 
on tracks, then reading the data to ensure it was 
recorded properly. 

In judging whether or not tracks are defective, 
the program does surface analysis the number of 
times you specify in the VERIFY parameter. If 
you omit the VERIFY parameter, surface analysis 
is done once. Tracks that cause reading or 
writing errors any time during surface analysis 
are considered defective. Defective tracks can be 
assigned alternates. The 5444 has six alternate 
tracks available; the 5445 has 60. If the program 
finds more than 6 or 60 defective tracks respectively, 
it considers the disk unusable and stops initializing it. 

The program also considers the disk unusable if either 
track 0 or 1 is defective. Tracks 0 and 1 are used only 
by the system and cannot have alternates assigned to 
them. For the 5445 the program also considers the 
disk unusable if any tracks in cylinder 0 are defective. 


Alternate Track Assignment 

Alternate track assignment is the process of assigning 
an alternate track to a defective track. If the Disk 
Initialization program finds a defective track 
during surface analysis, it assigns an alternate track 
to the defective track. The alternate is, in effect, 
a substitute for the defective track. Any time a 
program attempts to use the defective track, it 
will automatically use the alternate instead. Each 

5444 disk has six alternate tracks (tracks 2-7). Each 

5445 disk has 60 alternate tracks (tracks 4000-4059). 

If tracks become defective after a disk is initialized, 
another program (see Alternate Track Assignment 
Program) is used to assign alternate tracks. Disks 
need not be re-initialized to assign alternate tracks. 

ERASE Parameter (UIN) 

The ERASE parameter concerns alternate track 
assignment. It applies only to disks that have 
already been initialized and used, but which you 
are re-initializing using primary initialization. 

The condition of tracks on such disks has been 
tested at least once before (during the previous 
initialization) and tracks that were found to be 
defective during surface analysis were assigned 
alternates. The ERASE parameter, therefore, 
enables you to indicate whether you want the 
program to (1) retest the tracks to which alternate 
tracks are already assigned, or (2) leave the alter¬ 
nate tracks assigned without retesting the tracks. 

The parameter ERASE-YES means to retest. If 
you tell the program to retest, it erases any 
existing alternate track assignments, and tests 
all tracks as though the disk were new. 

The parameter ERASE-NO means not to retest. 

If you tell the program not to retest, it tests only 
those tracks to which no alternate tracks are as¬ 
signed. Alternate tracks previously assigned re¬ 
main assigned. 

Defective tracks are not retested if the ERASE 
parameter is omitted. 

CAP Parameter (UIN) 

The CAP parameter (5444 disk only) determines pack 
size when the pack is initialized. The CAP-HALF 
parameter means to initialize the pack to half capacity 
(100cylinders; 200 tracks) even if it is on a full capa¬ 
city drive. The CAP-FULL parameter means to ini¬ 
tialize the pack to full capacity (200 cylinders; 400 
tracks). The use of the CAP keyword forces ERASE- 
YES. 
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PACK Parameter (VOL) 

The PACK parameter (PACK-name) applies to 
primary and clear initializations only. During initiali¬ 
zation, the Disk Initialization program writes a 
name on each disk. It uses the name you supply 
in the corresponding PACK parameter. (One VOL 
control statement containing a PACK parameter 
is required for each disk.) 

The name can be any combination of standard 
System/3 characters except apostrophes, leading 
or embedded blanks, and embedded commas (due 
to their delimiter function). (See Appendix A for 
a list of standard System/3 characters.) Its length 
must not exceed six characters. The following are 
valid disk names: 0,F0001, 012, A1B9, ABC. 

In general, disk names are used for checking pur¬ 
poses. Before a program uses a disk, the disk 
name is compared with a name you supply 
(either in OCL statements or control statements 
required by the program). If the names do not 
match, the program halts and prints a message. 

In this way, programs cannot use the wrong disks 
without the operator knowing about it. 

ID (Identification) Parameter (VOL) 

The ID parameter (ID-characters) applies to primary 
and clear initializations only. It enables you to 
include a maximum of ten characters, in addition to 
the disk name, to further identify a disk. The char¬ 
acters can be any combination of standard System/3 
characters (Appendix A) except apostrophes, 
leading or embedded blanks, and embedded com¬ 
mas (due to their delimiter function). The informa¬ 
tion is strictly for your use. (It is not used for 
checking purposes by the system.) If you use 
the File and Volume Label Display program to 
print the disk name, it will also print the addition¬ 
al identification for you. 

NAME360 Parameter (VOL) 

The NAME360 parameter (NAME360-name) is used 
to specify a filename for data interchange with 
System/360-System/370. System/360-System/370 
can use data on a System/3 disk pack by treating the 
pack like a file. System/3 gives a default filename of 
SYSTEM/3.DATA. The NAME360 parameter can be 
used if you would like to code a filename of your 
own. 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the Disk Initialization program. 

// LOAD $INIT, code 
// RUN 

The code you supply depends on the location of 
the disk containing the Disk Initialization program. 
The codes are as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 
drive two 

F2 

Fixed disk on drive 

two 


EXAMPLES 

Primary Initialization of Two Disks 

Figures 25 and 26 are examples of the OCL state¬ 
ments and utility control statements needed for 
the primary initialization of two disks. 



Explanation: 

• Disk Initialization program is loaded from the fixed disk on 
drive one . 


Figure 25. OCL Load Sequence for Disk Initialization 

NAME360 can contain any of the standard System/3 
characters except apostrophes, blanks and commas. 

Its length must not exceed 44 characters. 
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Explanation: 


• The two disks on drive two are being initialized (UNIT- , F2,R2' 
in UIN statement). 

• The fixed disk (F2) will be given the name 2222 {PACK-2222 
in first VOL statement). 

• The removable disk (R2) will be given the name PAYROL 
(PACK-PAYROL in second VOL statement). Additional 
identifying information, 010270, will be written on the removable 
disk (ID-010270). 

Figure 26. Utility Control Statements for Primary Initialization 
of Two Disks 


MESSAGES FOR DISK INITIALIZATION 


Message 

Meaning 

INITIALIZATION 

ON XX COMPLETE 

This message is printed when initialization of a disk is 
complete. XX indicates the unit (R1, R2, Fl, F2, D1, 
or D2) on which the initialization is complete. 

INITIALIZATION ON XX 

TERMINATED 

This message is printed when initialization of a disk 
must be terminated for one of the following reasons: 


1. Cylinder zero is defective. 


2. More than 6 5444 tracks or 60 5445 tracks 

are defective. 


3. Possible disk hardware error exists. 


4. The program attempted to initialize the disk 

ten times without success. 


After this message is printed, halt 33 will occur. XX 
indicates the unit (R1, R2, Fl, F2, D1, or D2) on 
which the initialization is terminated. 

^ALTERNATE TRACKS 

ASSIGNED** 

PRIMARY TRACK XXX 

ALTERNATE TRACK XXX 

These two messages are printed when a primary track 
is defective and an alternate track is assigned to it. 

XXX indicates the tracks involved. 

UNRECOVERABLE ERROR; 
RE-INITIALIZING PACK 

This message is printed when the Disk Initialization 
program determines that the disk has not been 
initialized properly. The program will again attempt 
to initialize the disk correctly with ERASE-YES forced. 

The maximum number of times that the program will 
attempt to initialize a disk is ten. After that number of 
times, halt 33 occurs. 
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ALTERNATE TRACK ASSIGNMENT PROGRAM-SALT 


The Alternate Track Assignment program assigns alternate tracks to disk tracks that 
become defective after they are initialized. An alternate track is a track that can be 
assigned to replace another track. When the program assigns an alternate, it transfers 
the contents of the defective track to the alternate. The 5444 has 6 alternate tracks, 
the 5445 has 60. An alternate track can replace any track except 0 and 1 on the 5444 
or 0-19 of cylinder 0 on the 5445. 

The program has three uses. The control statements you must supply depend on 
the program use. 

The program uses and the situations to which they apply are as follows: 

Program Use Situation 

Conditional assignment Any time a disk track causes reading or writing 

Program tests the condition errors during a job, the system halts with a code 

of a track and assigns an indicating that a disk error has occurred. You 

alternate to it if it is defec- would now run the Alternate Track Assignment 

tive. (This is the normal program to do conditional assignment, 

use.) 

Unconditional Assignment (T) You have used the Alternate Track Assignment 
Program assumes the track program to do conditional assignment. The 

is defective and assigns test on the track indicated that the track was not 

an alternate to it without defective (an alternate, therefore, was not 

testing its condition. assigned). But the track still causes reading or 

writing errors, and you want to assign an 
alternate to it. 

A defective track was found, but all alternates 
are in use. You want to free an alternate so you 
can recover the data from the defective track. 
Before freeing the alternate, however, you would 
normally copy (to another disk) the file or 
library entry that uses the alternate. This saves 
the data that is already on the alternate. 


(7) Whenever you request an unconditional assignment or cancel prior assignment, any 
pending suspected defective tracks are checked (conditional assignment). 


Cancel prior assignment (T) 
Program cancels an 
alternate track assignment 
to free the alternate for 
use with another track. 
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CONTROL STATEMENT SUMMARY 


Conditional Assignment 


Unconditional Assignment 


Cancel Prior Assignment 


Control Statements'^ 

//ALT©PACK-name,UNIT-code,VERIFY-number 
//END 


// ALT©PACK-name,UNIT-code,ASSIGN- l, tr8c !‘ ,VERIFY-number(D 
//END « tr3CkS * 

ALT©PACK-name,UNIT-code,UNASSIGN- L traC !‘,[ ,VERIFY-number(D 

( tracks > 


// ALT' 
// END 


' For each use, the program requires the statements in the order they are listed: ALT, END. 


(2) 

v-y There can be only 6 ALT statements per job. 

(3) 

V-/The VERIFY parameter applies to the autom 


The VERIFY parameter applies to the automatic conditional assignment that follows the unconditional request. 
(See Program Use and Situation.) 


PARAMETER SUMMARY: ALT (ALTERNATE) STATEMENT 


PACK-name 


UNIT-code 


VERI FY-number 


ASSIGN-track 


ASSIGN-'track,track,. 


UNASSIGN-track 


UN ASSIGN-'track,track,. 


Name of the disk. 

Location of the disk. Possible 
codes are R1, FI, R2, F2, D1, D2. 

In testing the condition of a track, 
do surface analysis the number of 
times indicated (number can be 
1-255). If VERIFY parameter is 
omitted, do surface analysis once. 


Assign an alter¬ 
nate (uncon¬ 
ditionally) to 
one track. 

Assign one alter¬ 
nate (uncon¬ 
ditionally) to 
each track 
(maximum 
is six). 

Cancel one 
alternate track 
assignment. © 

Cancel two or 
more alternate 
track assign¬ 
ments (maximum 
is six). (D 


Use track num¬ 
bers 8-205 or 
8-405 (for 5444) 
20-3999 (for 
5445) to identify 
tracks. Tracks 
0-1 for the 5444 
or 0-19 for the 
5445 are used by 
the system and 
cannot be assign¬ 
ed alternates. 

Use track num¬ 
bers 8-405 (for 

5444) , or 
20-3999 (for 

5445) to which 
alternates are 
assigned. 


Before canceling an assignment, the program tests the con¬ 
dition of the track to which the alternate is assigned. The 
assignment is canceled if the test indicates that the track is 
not defective. If the test indicates that the track is defective, 
the program does not cancel the assignment unless the operator 
tells it to do so. 
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PARAMETER DESCRIPTIONS 
PACK Parameter 

The PACK parameter (PACK-name) tells the pro¬ 
gram the name of the disk containing the defective 
tracks. This is the name written on the disk by the 
Disk Initialization program. (See Disk Initialization 
Program.) 

The Alternate Track Assignment program com¬ 
pares the name in the PACK parameter with the 
name on the disk to ensure they match. In this 
way, the program ensures that it is using the right 
disk. 

UNIT Parameter 

The UNIT parameter (UNIT-code) indicates the 
location of the disk containing defective tracks. 
Codes for the possible locations are as follows: 


Code 

Meaning 

R1 

Removable disk on 
5444 drive one 

FI 

Fixed disk on 5444 
drive one 

R2 

Removable disk on 
5444 drive two 

F2 

Fixed disk on 5444 
drive two 

D1 

Removable disk on 
5445 drive one 

D2 

Removable disk on 
5445 drive two 


VERIFY Parameter 

The VERIFY parameter (VERIFY-number) con¬ 
cerns conditional assignment. (See Program Use 
and Situation for unconditional and cancel prior 
assignments.) It enables you to indicate the num¬ 
ber of times you want the program to do surface 
analysis before judging whether or not the track 
is defective. The number can be from 1-255. If 
you omit the parameter, the program does surface 
analysis once. 

Conditional Assignment 

Conditional assignment consists of testing the 
condition of a track (surface analysis) and, if 
the track is defective, assigning an alternate track 
to replace it. It is the normal use of the Alternate 
Track Assignment program. 


Situation. Conditional assignment applies to tracks that 
cause reading or writing errors during a job. Any 
time a track causes such errors, the system does 
the following: 

1. Stops the program currently in operation. 

2. Writes the track address in a special area on the 
disk. 

3. The system then halts with a halt code indicat¬ 
ing a permanent disk I/O error. You can then 
run the Alternate Track Assignment program. 

When you use the Alternate Track Assignment pro¬ 
gram to do conditional assignment, the program 
locates the tracks by using the addresses in the 
special area on disk. All disks, fixed and remova¬ 
ble, have such an area. The program will do 
conditional assignment for all tracks identified 
in the area (one at a time), as long as there are 
alternate tracks available for assignment. 

Surface Analysis. Surface analysis is a procedure the pro¬ 
gram uses to test the condition of tracks. It con¬ 
sists of writing test data on a track, then reading 
the data to ensure it was written properly. 

Before doing surface analysis, the Alternate Track 
Assignment program transfers any data from the 
track to an alternate track. This is the alternate 
that will be assigned if the track proves to be 
defective. 

In judging whether or not the track is defective, the 
program does surface analysis the number of times 
you specify in the VERIFY parameter. If you omit 
the parameter, the program does surface analysis 
once. If the track causes reading or writing errors 
any time during surface analysis, the program con¬ 
siders the track defective. 

Assignment of Alternate Tracks. If a track proves to be 
defective, the program assigns an alternate track. 
The alternate becomes, in effect, a substitute for 
the defective track. Any time a program attempts 
to use the defective track, it automatically uses 
the alternate instead. 

The 5444 has 6 alternate tracks; the 5445 disk has 
60. The program will not do conditional assign¬ 
ment if all alternate tracks are in use. 
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incorrect Data. If a track is defective, some of the data 
transferred to the alternate track could be incorrect. 
Therefore, when reading data from the defective 
track, the program prints all track sectors con¬ 
taining data that caused reading errors. Characters 
that have no print symbol are printed as 2-digit 
hexadecimal numbers. 

The following is an example: 

ABCDE GH123 56 . .. 

B A 

6 4 

Appendix A lists the characters in the standard 
character set and their corresponding hexadecimal 
numbers. 

To correct errors on the alternate track, use the Al¬ 
ternate Track Rebuild program. 

ASSIGN Parameter 

The ASSIGN parameter (ASSIGN-track) applies to 
unconditional assignment. It tells the program which 
tracks you want alternates assigned to. 

For 5444, you can assign alternates to any tracks 
except 0-7, which are for system use only. For 
5445 you can assign alternates to any tracks 
except 0-19 or 4000-4059; for system use only. 

The form of the ASSIGN parameter depends on the 
number of tracks you want to specify. For one 
track, use ASSIGN-track; for two tracks, use 
ASSIGN-'track,track'; and so on. You can specify 
up to six tracks. 


Use the track numbers 8-405 (for 5444) or 20-3999 
(for 5445) to identify the tracks. For example, the 
parameter ASSIGN'50,301,353' causes the program 
to assign alternate tracks to tracks 50, 301, and 353. 


Unconditional Assignment 

Unconditional assignment applies to tracks that 
occasionally cause read or write errors. Such 
tracks might not cause errors when tested by the 
Alternate Track Assignment program during con¬ 
ditional assignment. If they don't, the program 
will not assign alternate tracks to them. If you 
still want to assign alternates to these tracks, use 
unconditional assignment. In doing unconditional 
assignment, the program assigns alternates without 
first testing the condition of the tracks suspected 
of being defective. 


UNASSIGN Parameter 

The UNASSIGN parameter (UNASSIGN-track) 
applies to cancelling alternate track assignments. 

It identifies tracks for which you want the program 
to cancel assignments. 

You can cancel up to six assignments. The form of 
the UN ASSIGN parameter depends on the number 
of assignments you want to cancel. For one assign¬ 
ment, use UNASSIGN-track; for two assignments, 
use UNASSIGN-'track, track'; and so on. 

Use the track numbers 8-405 (for 5444) or 20-3999 
(for 5445) to identify the tracks. For example, the 
parameter UNASSIGN-'50,301,352' causes the 
program to cancel alternate-track assignments for 
tracks 50, 301, and 352. 

Cancel Prior Assignment 

Cancelling an alternate track assignment consists 
of transferring the data from an alternate track 
back to the original track (the track to which the 
alternate is assigned), therefore, freeing the alter¬ 
nate from being the substitute for the original 
track. 

Before transferring data back to the original track, 
the Alternate Track Assignment program tests the 
condition of the original track. If the test indicates 
that the track is defective, the program stops. 
Through the restart procedure you choose, you can 
tell the program to do one of four things (see 
IBM System/3 Disk System Halt Guide , GC21-7540) 


1. Cancel the assignment and transfer the data back 
to the original track regardless of the condition 
of the original track. 

2. Test the track again. 

3. Leave the assignment as it is. If there are other 
tracks for which you are cancelling assignments, 
the program continues with those. Otherwise, 
it ends. 

4. Cancel the job. 

Cancelling assignments is not often done. It ap¬ 
plies to cases where a defective track is found, but 
all six alternates are in use. To recover the data 
from the defective track, you might want to 
cancel an alternate track assignment to free the 
alternate track. Normally this involves copying, 
to another disk, a file or library entry that uses an 
alternate track, then freeing the alternate for use 
with the defective track you found. 
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OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the Alternate Track Assignment program. 

// LOAD $ALT r code 
// RUN 

The code you supply depends on the location of 
the disk containing the Alternate Track Assign¬ 
ment program. The codes are as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 

drive two 

F2 

Fixed disk on drive 

two 


Situation 

The sytem cancels a job if a defective track is found 
on the removable disk on drive one. (The name of 
the disk is Bl LLNG.) Before doing more jobs, the 
operator wants to use the Alternate Track Assign¬ 
ment program to check the condition of the track 
and assign an alternate to the track if it is defective. 
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Explanation: 

• Alternate Track Assignment program is loaded from the fixed 
disk on drive one. 

Figure 27. OCL Load Sequence for Alternate Track Assignment 


EXAMPLES 

Conditional Assignment 

Figures 27 and 28 are examples of the OCL state¬ 
ments and utility control statements needed for a 
conditional assignment as described in the following 
situation. 
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Explanation: 

• The name of the disk (BILLNG) and its location (removable 
disk on drive one) are indicated by the PACK and UNIT 
parameters in the ALT statement. 

• Because we omitted the VERIFY parameter from the ALT 
statement, the program does surface analysis once when it tests 
the condition of the tracks. 

Figure 28. Utility Control Statements for a Conditional 
Assignment 
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MESSAGES FOR ALTERNATE TRACK ASSIGNMENT 


Message 

Meaning 

ALTERNATE TRACK ASSIGNED 

This message is printed when an alternate track has been 
assigned to a defective track and the data has been trans¬ 
ferred to the alternate track. 

PRIMARY TRACK HAS BEEN TESTED 

OK 

This message is printed when it is determined that a 
primary track is not defective. 

PRIMARY TRACK STILL DEFECTIVE 

This message is printed when the Alternate Track Assignment 
program determines that the track is still defective. 

DATA TRANSFERRED BACK TO 

PRIMARY TRACK 

This message is printed when the data is transferred back to 
the primary track. 

**SECTOR WITH DATA ERROR** 

This message is printed when the Alternate Track Assignment 
program found an error when transferring data. The sector 
that has the error is printed out. 

**RECORD WITH DATA ERROR** 

This message is printed when the Alternate Track Assignment 
program found an error when transferring data. The record 
that has the error is printed out. 

PRIMARY TRACK xxx ALTERNATE 

TRACK yyy, UNIT-zz 

This message is printed after ALTERNATE TRACK 

ASSIGNED and DATA TRANSFERRED BACK TO PRIMARY 
TRACK, xxx is the primary track number, yyy is the alternate 
track number, and zz is the unit involved. 


no 




ALTERNATE TRACK REBUILD PROGRAM—$BUILD 


The Alternate Track Rebuild program enables you to correct data that could not be 
transferred correctly to an alternate track. One or more alternate tracks can be 
corrected during a program run. You must supply the control statements and data 
used to correct the errors. 

In writing control statements for this program, you will need the information printed 
by the Alternate Track Assignment program when it assigned the alternate track. 

The printed information tells you the name of the disk and numbers of the track 
and sectors suspected of containing incorrect data. It also includes the data from 
these sectors, which you can use to locate incorrect data. On the 5445, fixed 
record refers to a physical 256-byte record, similar to the sector on the 5444 


CONTROL STATEMENT SUMMAR 


yO 


// REBUILD PACK-name,UNIT-code,TRACK-location, LENGTH- 
number.DISP-position 

Substitute data 


// END 


O 


To replace characters 1-12 and 75-78 of a sector, you can use 
either of the following: 


1, Use one REBUILD statement to replace all the characters 
with a LENGTH parameter of 78. 

2. Use one REBUILD statement for every set of positions 1 
you correct. 


The data you want to substitute must follow the REBUILD 
statements to which it applies. The order of the statements 
and data in the preceding example would be: 

// REBUILD statement 

data for positions 1-78 

// END 

// REBUILD statement for positions 1-12 

data 

// REBUILD statement for positions 75-78 

data 

// END 


PARAMETER AND SUBSTITUTE DATA SUMMARY 

REBUILD Statement 


PACK-name 

Name of the disk. 

UNIT-code 

Location of the disk. Possible codes are 

R1, FI, R2, F2, D1, D2. 

TRACK-location 

5444 Disk Unit— Number of track and 
sector containing incorrect data. 

Number is printed by Alternate Track 
Assignment program. Track number 
must be three digits; sector number 
must be two digits. (TRACK-01109 
means track 11 sector 9). 


5445 Disk Unit— Number of track and 
fixed record containing incorrect 
data. Number is printed by Alternate 

Track Assignment program. Track 
number must be four digits; fixed 

Record number must be two digits. 
(TRACK-011109 means track 111, 
fixed record 9). 

LENGTH-number 

Number of characters being replaced. 
Number can be 2-256 and must be a 
multiple of 2 (2, 4, 6, etc.). 

DISP-position 

Position of the first character being re¬ 
placed in the sector. Position can be 

1-255. 

Substitute Data 


Code each character in hexadecimal form. Follow every second 
character, except the last, with a comma. EXAMPLE: The 
numbers 123456 would be coded as F1F2,F3F4,F5F6. 
(Appendix A lists the hexadecimal codes for System/3 charac¬ 
ters.) 
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PARAMETER AND SUBSTITUTE DATA 
DESCRIPTIONS 

PACK Parameter 

The PACK parameter (PACK-name) tells the pro¬ 
gram the name of the disk that contains the alter¬ 
nate track being corrected. This name is the one 
written on the disk by the Disk Initialization 
program. 

The Alternate Track Rebuild program compares the 
name in the PACK parameter with the name on the 
disk to see if they match. In this way, the pro¬ 
gram ensures that the program is using the right 
disk. 

UNIT Parameter 

The UNIT parameter (UNIT-code) indicates the 
location of the disk that contains the alternate 
track being corrected. Codes for the possible 
locations are as follows: 


Code 

Meaning 

R1 

Removable disk on 
5444 drive one 

FI 

Fixed disk on 5444 

drive one 

R2 

Removable disk on 

5444 drive two 

F2 

Fixed disk on 5444 
drive two 

D1 

Removable disk on 
5445 drive one 

D2 

Removable disk on 

5445 drive two 


TRACK Parameter 

The TRACK parameter (TRACK-location) identifies 
the track and sector that contains the data being 
corrected. The defective track, not the alternate 
track, is the one you refer to. Referencing the 
defective track is the same as referencing the alter¬ 
nate track. 

For the 5444 disk, the possible track numbers are 
008-405. Always use three digits. The possible 
sector numbers are 00-23. Always use two digits. 
The track number must precede the sector number. 
For example, the parameter TRACK-11019 means 
track 110, sector 19. 


For the 5445 disk, the possible track numbers are 
0020-3999. Always use four digits. The possible 
fixed record numbers are 01-20. Always use two 
digits. The track number must precede the fixed 
record number. For example, the parameter 
TRACK-111019 means track 1110, record 19. 

Track and sector numbers are printed by the Alter¬ 
nate Track Assignment program when it prints data 
from sectors that contain incorrect data. 

LENGTH Parameter 

The LENGTH parameter (LENGTH-number) tells 
the program how many characters you are replacing 
in the sector or fixed record. You must replace 
characters in multiples of 2 (2, 4, 6, and so on). The 
maximum is 256, which is the capacity of a sector 
or fixed record. 

Length applies to characters that occupy consecu¬ 
tive positions in the sector or fixed record. If the 
characters you want to replace do not occupy con¬ 
secutive positions, you must either replace all inter¬ 
vening characters or use more than one REBUILD 
statement. For example, to replace characters 10-11 
and 24-25 in a sector or fixed record, you can do 
either of the following: 

1. Use one REBUILD statement to replace charac¬ 
ters 10-25 (LENGTH-16). 

2. Use two REBUILD statements to replace charac¬ 
ters 10 11 (LENGTH-2) and 24-25 (LENGTH-2). 

DISP (Displacement) Parameter 

The DISP parameter (DISP-position) indicates the 
position of the first character being replaced in the 
sector or fixed record. The position of the first 
character is 1; the position of the second character 
is 2, and so on. The maximum position you can 
specify is 255. 

Beginning at the position you indicate, the Alternate 
Track Rebuild program replaces the number of char¬ 
acters you indicate in the LENGTH parameter. 
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Substitute Data 

After each REBUILD statement, you must code the 
substitute characters that apply to that statement. 
The characters must be in hexadecimal form. Ap¬ 
pendix A shows the hexadecimal codes for the 
System/3 character set. 


EXAMPLES 

Correcting Characters on an Alternate Track 

Figures 29 and 30 are examples of the OCL and 
utility control statements needed for correcting 
characters on an alternate track. 


Include a comma after every second character. 

For example, the data FI F2,F3F4,F5F6 represents 
123456. FI is the hexadecimal form of 1; F2 is 
the hexadecimal form of 2; and so on. 

Code only the number of characters you indicated 
in the LENGTH parameter in the REBUILD state¬ 
ment. 

Note: If the LENGTH parameter of the REBUILD 
statement exceeds 38, at least two substitute data 
cards are required. Each substitute data card, except 
the last one, must be completely filled with data and 
must have a comma in column 95 and a blank in 
column 96. If the 1442 is the only input device, 
it is possible to have only one substitute data card. 



Explanation: 

• Alternate Track Rebuild program is loaded from the fixed disk 
on drive one. 

Figure 29. OCL Load Sequence for Alternate Track Rebuild 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the Alternate Track Rebuild program. 

// LOAD $BUILD, code 
// RUN 

The code you supply depends on the location of 
the disk containing the Alternate Track Rebuild 


program. 

The codes are as follows: 

Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 

drive two 

F2 

Fixed disk on drive 

two 


Alternate Track Rebuild Program—$BUI LD 
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Explanation: 

• The name of the removable disk (BILLNG) and its location (drive one) are indicated in the PACK and UNIT 
parameters in the REBUILD statement. 

• The sector containing the incorrect characters is sector 0 of the alternate track assigned to track 20 (TRACK-02000). 
The character in position 120 is the first character being replaced (DISP-120). 

• The characters in positions 120 through 123 in sector 0 are beirfg replaced (LENGTH-4). 

• The substitute characters follow the REBUILD statement. They are G (C7), H (C8), l(C9), and 1 (FI). 

Figure 30. Utility Control Statements for Correcting Characters on an Alternate Track 


Situation 

Assume that the Alternate Track Assignment pro¬ 
gram printed the following information: 


**SECT0R WITH DATA ERROR** 

TRACK 
02000 


0000000000000000000000000000002000100008300000000000000000000000000000000000000000000000 
000000000000000000000000000000024888C210010000000000000000000000000000000000000000000000 

oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooc 

0000000000000000000000000000000000000000000000000000000000000000000000000000005A 


!•••«••• 10 ..20........30..40..50*... 60 . . ..70.80.88 

Z ABCDEFGHI JK LMNOPQR STUVWXYZ 0123456789 

FFFFFF903B524677 DC CCCCCCD DDDDDDEE EEEEEE FFFFFFOOOOOO 

FEDCBAFBEDFEF70 5 FO ABCDEFO ABCDEF01 ABCDEF ABCDEFOOOOOO 


[55202A 


It means that errors were detected in sector 0 of 
track 20. (Assume the name of the disk is BILLNG.) 

In checking the characters printed by the program, 
you found that the characters in positions 120-123 
in the sector are incorrect and you want the oper¬ 
ator to run the Alternate Track Rebuild program 
to correct them. 
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FILE AND VOLUME LABEL DISPLAY PROGRAM—$LABEL 


The File and Volume Label Display program has two uses: 

1. Print the entire Volume Table of Contents (VTOC) from a disk. 

2. Print only the VTOC information for certain data files. 

In both cases, the program also prints the name of the disk. 

The printed VTOC information is a readable, up-to-date record of the contents of 
the disk. There can be any number of reasons why you might need the information. 
Some of the more common ones are as follows: 

1. Before re-initializing a disk, you might want to check its contents to ensure that 
it contains no libraries, permanent data files, or temporary data files. 

2. You want to find out what disk areas are available for libraries or new files. 

3. You want specific file information, such as the file name, designation (permanent, 
temporary, scratch), or the space reserved for the file. 

The control statements you supply for the program depend on the program use. 


CONTROL STATEMENT SUMMARY 


Uses 


Control Statement 


© 


Print entire // DISPLAY UNIT-code, LABEL-VTOC 

VTOC //END 


Print only file // DISPLAY UNIT-code, LABEL- } ™ ename | © 
,, /filenames) 

information // END 

from VTOC 


© 


For each use, the program requires the statements in the 
order they are listed: DISPLAY, END. 


The number of filenames you list for a program run may not 
exceed 20. (VTOC is considered as one filename.) 


PARAMETER SUMMARY (DISPLAY STATEMENT) 

UNIT-code 

Location of the disk containing 
the VTOC information being 
printed. Possible codes are R1, 
FI, R2, F2, D1, D2. 

LABEL-VTOC 

Print entire contents of VTOC. 

LABEL-filename 

Print VTOC information for 
one file. 

LABEL-'filename/Filename,... 

Print VTOC information for 
more than one file. CD 

© The number of filenames you list for a program run may not 
exceed 20. (VTOC is considered as one filename.) 
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PARAMETER DESCRIPTIONS 
UNIT Parameter 

The UNIT parameter (UNIT-code) indicates the 
location of the disk containing the VTOC informa¬ 
tion being printed. Codes for the possible locations 
are as follows: 


Code 

Meaning 

R1 

Removable disk on 

5444 drive one 

FI 

Fixed disk on 5444 

drive one 

R2 

Removable disk on 

5444 drive two 

F2 

Fixed disk on 5444 

drive two 

D1 

Removable disk on 

5445 drive one 


LABEL Parameter 

The LABEL parameter indicates the information 
you want printed: the entire contents of the VTOC 
or only the information for certain files. The VTOC 
is an area on disk that contains information about 
the contents of the disk. Every disk, fixed and re¬ 
movable, contains a VTOC. 

Entire Contents of VTOC 

The parameter LABEL-VTOC means to print the 
entire contents of the VTOC. The meaning of the 
information the program prints is given in the 
following chart. Headings that are listed are the 
ones printed by the program to identify the informa¬ 
tion. Figures 31 and 32 are examples of VTOC 
printouts. 

If the program needs more than one page to list 
the file information it prints the headings for the 
file information at the top of each new page. 


D2 Removable disk on 

5445 drive two 


PACK-11 i 111 


ID-ANOtRSuN 


NO. UF AL TERNA TE TRACKS AVAlLABLt-2 
TRACKS WITH ALTERNATt ASSIGNtU-302,200 
DEFECTIVE ALTERNATE TRACKS-3t5 
DtViCt CAPACITY-400 

LIBRARY EXTENT— START END EXTENUtU END 
0GB 0 11 027 

AVAILABLE SPACE ON PACK 
LOCATION TRACKS 
C2B 367 

399 001 

401 001 


PACK-Hi ill 

unit- 

R1 

UATt 

11/11/70 


FILE 

file 

KEEP 

FILE 

REC 

KEY 

KEY 

NAME 

DATfc 

TYPt 

TYPt 

LtN 

LEN 

LUC 

COST 

09/21/71 

T 

S 

0128 



MASTER 

03/14/71 

P 

s 

0128 



EMPLOYEE 

12/07/70 

P 

i 

0128 

08 

0005 

UPDATE 

-00/44/71 

T 

I 

0128 

05 

0005 

PARTS 

08/09/71 

T 

u 

0128 



SERIAL 

08/ 16/71 

T 

s 

0128 



ADDRESS 

09/21/71 

T 

s 

0080 



BACKUP 

09/29/71 

S 

s 

0128 




Figure 31. VTOC Printout Example 


NEXT AVAIL 

NEXT AVAIL 

INDEX 

DA I A 

VOL 

RtLORD 

KtY 

STAR \ 

End 

START 

END 

SEO 

405/11/129 




hG5 

405 

00 

404/11/129 




404 

404 

00 

**** 

40 2/C 1 / 129 

40/1 

402 

403 

403 

02 

396/11/129 

395/CC/185 

395 

395 

396 

396 

00 

**** 




400 

400 

01 

398/ 11/129 




398 

398 

00 

397/06/065 




397 

39 7 

00 

399/11/129 




399 

399 

00 






155201A 
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PACR-UlOlDi 


lu- 


OF ALTERrtATc TRACKS AVAlLAbLt-6u 


AVAlLAbLt SPACE UN PACK 


luC a t i Ui\i Tracks 


ooi/uo 3941 


199/OU 0002 


PACK-OIu 

FlLt 

101 Ui>*n~ 

FlLt KEEP 

u 1 

FlLt 

OATt 

Rto 

09//9//1 
KtY K.tY 

mexi avail 

NtXT AVAIL 

lnldtX 

if ak r t^o 

OATA 

START EMU 

VUL 

SEW 

NAME 

OATt TYPE 

TYPt 

; LEM 

LE<* LOC 

RtCURO 

KEY 

COST 

09/^i/7l 

T 

D 

0126 


***** 




199/10 

199/19 

00 

HASTcR 

03/14/71 

P 

0 

0096 


***** 




199/08 

199/09 

00 

EMPLuYEt 

12/07/70 

P 

I 

OObO 

Ob 0006 

199/03/01/101 

199/02/01/019 

199/ Ol 

199/02 

199/03 

199/07 

00 

PARTS 

08/09/71 

T 

0 

02b6 


***** 




198/18 

198/19 

00 

AODRtSS 

09/21/71 

r 

s 

u03o 


196/16/01/061 




198/16 

198/17 

01 

SERIAL 

08/16/71 

T 

s 

0 100 


196/01/01/201 




198/01 

i98/1S 

00 

UPOaTe 

09/14/71 

s 

I 

0200 

03 000/ 

199/01/02/14b 

199/00/Ol/Olb 

199/00 

199/00 

199/01 

199/01 

Oo 


Figure 32. VTOC Printout Example of 5445 Disk 
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MEANING OF VTOC INFORMATION 


Heading 


Meaning 


PACK-name 


Name of the disk. 


I D-characters 


Additional disk identification (if any). 


NUMBER OF ALTERNATE TRACKS Number of alternate tracks available for assignment. 

AVAI LABLE-number 

TRACKS WITH ALTERNATE ASSIGNED Numbers of primary tracks that have been assigned an alternate. 

DEFECTIVE ALTERNATE TRACKS Numbers of the alternate tracks that are defective. 


DEVICE CAPACITY-number 


Disk drive capacity (number of tracks) - 5444 disk only. 


LIBRARY EXTENT 


Boundary of libraries on the disk. (If the 5444 disk contains no libraries, 
these headings are not printed.) 

Track on which library begins. |f 5444 disk contains both source and 

object library, START refers to begin- 
Track on which library ends. n ing of source library and END refers 

to end of object library. 


EXTENDED END 


Object library only (5444 disk only). Track on which extension to library 
ends. When object library is full, temporary entries can be placed in space 
following end of library, provided that space is available. 


AVAILABLE SPACE ON PACK 


Available disk areas. 


LOCATION 


First track in available area (5444). First cylinder/track in available area (5445). 


TRACKS 


Number of tracks available. 


PACK-name 


Name of the disk. 


UNIT-code 


Location of the disk containing the VTOC information. 


DATE-xx/xx/xx 


Program level date 


FILE NAME 


Name that identifies file in VTOC. 


FILE DATE 


Date given the file when file was placed on disk. 


KEEP TYPE 


FILE TYPE 


REC LEN 
KEY LEN 


File designation: 

P = permanent 
T = temporary 
S = scratch 
File type: 

I = indexed 

S = sequential 
D = direct 

SS = split cylinder, sequential 

SD= split cylinder, direct 
B = basic file 

Number of characters in each record in file. 

Indexed files only. Number of characters in each record key. 


KEY LOC 


Indexed files only. Position in record occupied by last character of record 
key. 
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Heading 

Meaning 

NEXT AVAIL RECORD 

Beginning location of next available record in file. For 5444 disk, location is 
track, sector, and position within sector. For 5445 disk, location is cylinder, 
track, fixed record, and position within record. 

EXAMPLE: 099/18/006 = track 99, sector 18, position 6 .^ 


050/02/12/006 = cylinder 50, track 2, fixed record 12, 
position 6.0 

NEXT AVAIL KEY 

Indexed files only. Beginning location of next available record key in index 
portion of file. For 5444 disk, location is track, sector, and position within 
sector. For 5445 disk, location is cylinder, track, fixed record, and position 
within record. xtn 

EXAMPLE: 090/10/006 = track 90, sector 10, position 6 .W 


052/03/10/006 = cylinder 52, track 3, fixed record 10, 
position 6 .^ 2 ^ 

INDEX 

START END 

Indexed files only. For 5444 disk, tracks on which index starts (START) and 
ends (END). For 5445 disk, cylinder/track on which index starts (START) 
and ends (END). 

DATA 

START END 

Disk area reserved for the file. START is the first 5444 track or 5445 cylinder/ 
track of the area. END is the last 5444 track or 5445 cylinder/track. For 
indexed files, this refers to the data portion of the file. 

VOL 

SEQ 

VOL SEQ applies to multivolume files only. It indicates the order of this disk 
as it relates to the other disks containing the remaining portion of the file. 

0 If the first byte of the next available record occurs in the next track after the end track of DATA START END then this 
field will contain ****. 

h the first byte of the next available key occurs in the next track after the end track of INDEX START END, 
then this field will contain ****. 


File Information Only 

The parameter LABEL-filename or LABEL-'file- 
names' means to print certain file information 
from the VTOC. For one file, use LABEL-filename; 
for two files, use LABEL-'filename,filename'; and so 
on. (Use the names that identify the files in the 
VTOC.) You can list 20 filenames for a program 
run. The statement length, however, is restricted 
to 96 characters. 

The program prints the file information for each 
of the files you list. This is the information des¬ 
cribed for the headings PACK name and FILE 
LABEL in the chart. Meaning of VTOC Information. 

If the program needs more than one page to list the 
file information, it prints headings for the file 
information at the top of each new page. 


OCL CONSIDERATIONS 

The following OCL statements are used to load the 
the File and Volume Label Display program. 

// LOAD $LABEL,code 
// RUN 

The code you supply depends on the location of 
the disk containing the utility program. The codes 
are as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 


one 

R2 

Removable disk on 
drive two 


F2 Fixed disk on drive 

two 
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EXAMPLES 


Printing VTOC Information for Two Files 

Figures 33 and 34 are examples of the OCL state¬ 
ments and utility control statements needed to 
print VTOC information for two files. 



Explanation: 

• The File and Volume Label Display program is loaded from the 
fixed disk oh drive one. 

Figure 33. OCL Load Sequence for File and Volume Label Display 
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Explanation: 

• The files for which information is printed are named Bl LLNG 
and INV01 (LABEL-'BILLNGJNVOI' in DISPLAY statement). 

They are located on the removable disk on drive one (UNIT-R1). 

Figure 34. Utility Control Statements for Printing VTOC information for Two Files 
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FILE DELETE PROGRAM—$DELET 


The File Delete program hat, three uses: 

• Remove all files from a disk. 

• Remove only the files you name. 

• Scratch file references in the Volume Table of Contents (VTOC). Deleting files 
frees the space they occupy for use by new files. 

The program may be used on temporary, scratch and permanent files. To delete per¬ 
manent files, you must use the File Delete program. You can scratch temporary files 
by using the File Delete program or by changing the file designation from temporary to 
scratch (using the OCL keyword RETAIN) when you use the file. 

The control statements you supply for the File Delete program depend on the function 
to be performed. 

The SCRATCH statement does not erase files from the disk. It changes their designa¬ 
tion to scratch (S) in the Volume Table of Contents (VTOC). By doing this, the prog¬ 
ram makes the areas that contain the files available for other files or for system prog¬ 
rams. A halt will occur if an attempt is made to create a new multivolume file that 
will have the same label on disk as an existing single volume file, or an attempt is made 
to create a single volume file bearing the same label as an existing multivolume file. 

The halt will occur even though the existing file is a scratch file. If a REMOVE state¬ 
ment is used, files are erased from the VTOC. The REMOVE statement can also be 
used to erase files from the disk. No file ii physically scratched or removed from the 
VTOC until end of job has occurred. 
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CONTROL STATEMENT SUMMARY 


Use 


Control Statements 


© 


Scratch all // SCRATCH PACK-name, UNIT-code, LABEL-VTOC 

files in the //END 

VTOC. 

Scratch only //SCRATCH PACK-name, UNIT-code, LABEL-filename, DATE-date 
one file in 
the VTOC. 

Scratch 
multiple 
files in 
the VTOC 


© 


// SCRATCH PACK-name, UNIT-code, LABEL- j[ 


Remove all // REMOVE PACK-name, UNIT-code, LABEL-VTOC, DATA--{ or 
files from 
disk 

// END 

// REMOVE PACK-name, UNIT-code, LABEL 


Remove 
only the 
files named 
from disk 


filename 

'filenames 




NO ) 


or l 


YES \ 


© 

( NO 

DATE-date, DATA- • 

< or 


/ YES 


// END 


© 

© 


For each use, the program requires the statements in the order they are listed: SCRATCH, END, or 
REMOVE, END. 

Use this form of the SCRATCH or REMOVE statement when two or more files have the same name and 
you want to delete one of them. 
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PARAMETER SUMMARY 



PACK-name 

Name of the disk. 


UNIT-code 

Location of the disk, 
codes are R1, FI, R2, 

Possible 

F2, D1, D2. 

LABEL-VTOC 

Scratch or remove all files 
from the VTOC. 

LABEL-filename 

Scratch or remove — 
only the file 
named in the VTOC. 

Use names 

that 

identify 

LABEL-'filename,filename,.. 

. Scratch or remove 
only the files 
named in the 

VTOC. - 

files in 

VTOC. 

© 

DATE-date 

Date of the file being deleted. 

Date must be a 6-digit number. 
EXAMPLE: DATE-062070 
means June 20, 1970. 

/-NO 'I 

DATA - < or > 

^ YES ' 

Delete files from VTOC 
and/or disk 

Ci) These are the names you gave the files when you placed them 
on disk. 


UNIT Parameter 

The UNIT parameter (UNIT-code) tells the pro¬ 
gram the location of the disk containing the files 
being deleted. Codes for the possible locations 
are as follows: 


Code 

Meaning 

R1 

Removable disk on 
5444 drive one 

FI 

Fixed disk on 5444 
drive one 

R2 

Removable disk on 
5444 drive two 

F2 

Fixed disk on 5444 
drive two 

D1 

Removable disk on 
5445 drive one 

D2 

Removable disk on 
5445 drive two 


LABEL Parameter 

The LABEL parameter identifies the files you want 
to delete from the disk. Its form depends on the 
files you are deleting: 


PARAMETER DESCRIPTIONS 


Form Files Deleted 

LABEL-VTOC All of them. 


PACK Parameter 

The PACK parameter (PACK-name) tells the pro¬ 
gram the name of the disk that contains the files 
being deleted. The name you supply in this para¬ 
meter is the one written on the disk by the Disk 
Initialization program. 

The File Delete program compares the name in the 
PACK parameter with the name on the disk to en¬ 
sure they match. In this way, the program ensures 
that it is using the right disk. 


LABEL-filename Only the file that is 

named. The name can 
apply to more than one 
file. If it does, all of 
those files are deleted 
unless you use a DATE 
parameter to identify a 
particular one. 
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Form 


Files Deleted 

LABE L-'filename,filename,...' 

Only the files that 
are named. A name 
can apply to more 
than one file. If it 
does, all of those files 
are deleted. You can 
list as many filenames 
as the statement can 
hold; the statement 
length, however, is 
restricted to 96 char¬ 
acters. Additional 
REMOVE or 
SCRATCH statements 
may be used for ad¬ 
ditional filenames. 

The maximum num¬ 
ber of files that can be 
deleted in one run is 40. 


DATA Parameter 

The DATA parameter lets you remove the files 
specified directly from the disk as well as from 
the VTOC. 

If YES is coded in this parameter, the file specified 
will be removed from the disk and any reference to 
it in the VTOC will be removed. In addition, a 
message will be printed on the system log device for 
each file removed from the disk in this format: 

'DATA REMOVED FOR FILE XXXXXX 
DATE 000000' 

DATA-YES should only be used if file security is 
required. The time needed to remove the data is 
much greater than the time needed to remove the 
VTOC entry. 

If NO is coded in this parameter, the file specified 
will not be removed from the disk. However, any 
reference to it in the VTOC will be removed. If 
this parameter is not used, DATA-NO is assumed. 


DATE Parameter 

The DATE parameter can only be used with 
LABEL-filename. The DATE parameter (DATE- 
date) applies to two or more files that have the 
same name. It tells the program the date of the 
one you want to delete. 

Every file on disk has a date, which is given to the 
file at the time it is created. When two or more 
files have the same name, the dates are used to 
tell one file from another. 

If the pack has more than one file with the name you 
list in the LABEL parameter, they will all be deleted 
unless you use the DATE keyword and parameter to 
indicate a particular file. If the DATE keyword is 
used, only one filename can be given in the LABEL 
parameter for that control statement. 

The date is a 6-digit number: two digits for day, 
two for month, and two for year. Day, month, 
and year can be in one of two orders: (1) month, 
day, year, and (2) day, month, year. For example, 
061870 and 180670 both mean June 18, 1970. 

In the DATE parameter, be sure to specify day, 
month, and year in the same order as they were 
specified when you placed the file on disk. 
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EXAMPLES 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the File Delete program: Deleting One of Several Files Having the Same 

Name 

// LOAD $DELET,code Figures 35 # 36, and 37 are examples of the OCL 

H RUN statements and utility control statements needed 

to delete one of several files having the same name 


The code you supply depends on the location of the 
disk containing the utility program. The codes 

as described in the following situation. 

are as follows: 


Situation 

Code 

Meaning 

Assume that three files on a removable disk have 
the same name: INV01. The dates of these files 

R1 

Removable disk on 
drive one 

are 6/16/70, 8/18/70, and 11/15/70. You want to 
delete the version dated 6/16/70. 

FI 

Fixed disk on drive 



one 


R2 

Removable disk on 

drive two 


F2 

Fixed disk on drive 



two 



1 4 8 12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 
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Explanation: 

• File Delete program is loaded from the fixed disk on drive one. 


Figure 35. OCL Load Sequence for File Delete 



Explanation: 

• Disk that contains the file being deleted is named 00001 (PACK-00001 in SCRATCH statement). 

• Because two other files have the name INV01, the date (061670) is needed to complete the identification 
of the file you want to delete (LABEL-INV01 and DATE-061670). 

• The removable disk containing the file to be deleted is on drive one (UNIT-R1). 

Figure 36. Utility Control Statements to Delete One Version of a File 
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Explanation: 

• A REMOVE statement is used instead of a SCRATCH statement. 

• Disk that contains the file being deleted is named 00001 
(PACK-00001 in REMOVE statement). 

• Because two other files have the name INV01, the date (061670) 
is needed to complete the identification of the file you want to 
delete (LABEL-INV01 and DATE-061670). 

• The removable disk containing the file to be deleted is on drive 
one (UNIT-R1). 

• The YES specification in the DATA parameter will delete all 
data from the disk containing information on the specified file. 


Figure 37. Utility Control Statement to Delete One Version of a File Using a REMOVE Statement 
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DISK COPY/DUMP PROGRAM-$COPY 


The Disk Copy/Dump program has three general uses. The control statements you 
must supply depend on the program use. 

The program uses and most common reasons for them are as follows: 


Program Use 

Copy entire contents of one 
disk to another. 


Copy a data file from one 
disk to another, or from one 
area to another on same disk. 


Print all or part of a data file. 


Common Reasons 

Provide a reserve disk in case something 
happens to the original disk. Important 
disks, such as those containing your libraries 
and permanent data files, are normally the 
ones you would copy. 

Any of the following: 

• Provide a reserve file in case something 
happens to the original file. 

• Move a file to a larger disk area. 

• Re-organize the data portion of an in¬ 
dexed file. (Data in the copy of the file 
is re-organized; the original file is un¬ 
changed.) 

• Delete records from a file. (Records are 
omitted from the copy of the file; the 
original file remains unchanged.) 

Provide a printed copy of the records in a 
file, perhaps for use in checking the records 
for errors. 


The OCL sequence used to load the program describes the disk file being copied or 
printed. If you are copying the file to disk, the file being created must also be des¬ 
cribed in the OCL sequence. 


Disk Copy/Dump Program- $CGPY 
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CONTROL STATEMENT SUMMARY 


Control Statements ' 


Copy an Entire Disk // COPYPACK FROM-code,TO-code 


Copy a Data File 


Copy and Print 
a Data File 


// END 


// COPYFILE 


// END 


// COPYFILE 


// END 


OUTPTX-) (DELETE) ft) \ N0 I (7) { NC 

-or- [dISKa -or- yposition,character'/^REORG- < -or- j- ,V»yW0RK- 1 -or 
OUTPUT- OMIT- \ /YES) YE 


NO / 

-or- > CD 
YES) 


OUTPUT- 


OUTPTX- 


or- > BOTH J -or- ^position,character', v^re0RG-YES,'-'WORK- < -or- 


°f © 


(DELETE- 


Copy a Data File, //COPYFILE -J -or- rBOTHJ -or- vposition,character', v-^REORG-YES, 
But Print Only a (OUTPUT-) (OMIT- ) 

Part of the File // SELECT KEY.FROM-'key' vi) -1 


.©WORK.)™!© 


(-; ^ ('-"Vi- j 

// SELECT KEY.FROM-'key'd;' 

-or- x-v 

// SELECT KEY,FROM-‘key',TO-'key'd/ 

-or- 

// SELECT RECORD,FROM-number 
-or- 

// SELECT RECORD,FROM-number,TO-number 

// SELECT PKY,FROIVI-'key’ © 

-or- 

// SELECT PKY,FROM-'key',TO-'key' ( 7 ) 

//END 



One of these' 


One of these v 


Print an Entire Data //COPYFILE -j -or- V PRINT 

File / OUTPUT-) 

// END 

( OUTPTX- i 

Print Only aPart //COPYFILE < -or- > PRINT - 

of a Data File (OUTPUT-) 

// SELECT KEY, FROM-'key'd) 

-or- 

// SELECT KEY,FROM-'key',TO-'key' d) /Jn 

-or- One of these 

// SELECT RECORD.FROM-number 
-or- 

//SELECT RECORD,FROM-number,TO-number 

// SELECT PKY.FROM-'key'CD 
-or- 

// SELECT PKY,FROM-'key',TO-'key' d) _ 

// END 

©The program uses include the possible combinations of copying and printing files. 

^^DFor each use, the program requires the control statements in the order they are listed: COPYPACK, END; COPYFILE, END; and 
COPYFI LE,SELECT,END. 

G^Needed only if you want to delete a certain type of record. DELETE cannot be used with direct files. 

Applies only to indexed files. When OUTPUT-BOTH is specified, REORG-YES is required. 

GDwORK-YES applies if you are copying the file from one removable disk to another using the same disk drive (drive one). WORK-NO 
applies if you are copying the file from one area to another on the removable disk on drive one. 

© Identifies the portion you want to print. 

Index files with packed keys. 
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PARAMETER SUMMARY 


COPY PACK Statement 


FROM-code 


TO-code 


Location of disk to be copied. Possible codes are Rl, FI, R2, F2, D1, D2. 
Location of disk to contain the copy. Possible codes are Rl, FI, R2, F2, D1, D2. 


COPY FILE Statement 
OUTPUT-DISK 
OUTPUT-PRINT 
OUTPUT-BOTH C‘ 


\ DISK j 
OUTPTX- j PRINT 
I BOTH \ 


Copy the file from one disk to another, or from one area to another on the same di 


Print the entire file or only part of the file. 1 


Copy the file from one disk to another, or from one area to another on the same disk 
Also print the entire file or only part of it. 

Printed output will be displayed in hexadecimal values. 


isk .Q 

isk.(7) 


DELETE-'position,character' 

-or- 

OMIT-'position, character' 


reorg-no(T) 

1G-YES ©© 

k-no(T) 
k-yes(T) 


reorg-yes 


WORK-NO 


SELECT Statement 


These parameters are optional. It means that all records with the specified character in the speci¬ 
fied record position are deleted. DELETE causes deleted records to be printed. OMIT causes 
deleted records not to be printed. Position can be any position in the record (the first position 
is 1, second 2, and so on). The maximum position is 9999. 


Indexed files only. Copy records in the same way as they are organized in the original file 
(the file from which the records are copied). 

Indexed files only. Reorganize the records so that the records in the data portion of the 
file are in the same order as their keys are listed in the index. 

Required for copying a file from one area to another on a removable disk on drive one (Rl or DI). 
It means: do not use a work area. 

Required for copying a file from one removable disk on drive one to another removable 
disk on that drive. It means: use a work area on the fixed disk on drive one or on the 
removable disk on drive one if the file being copied is on the 5445. Rl must have a 
minimum of 198 contiguous unused tracks. 


,FROM-'key' 


(key) 

) PKY (• 


FROM-'kev',TO-'key' 


RECORD,FROM-number 

RECORD,FROM-number, 

TO-number 


Indexed files only. Print only the part of the file from the record key that is specified 
in the FROM parameter to the end of the file. 

Indexed files only. Print only the part of the file between the two record keys that are 
specified in the FROM and TO parameters (including the records indicated by the 
parameters). To print only one record, make the FROM and TO record keys the same. 

Print only the part of the file from the relative record number specified in the FROM 
parameter to the end of the file. 

Print only the part of the file between the relative record numbers indicated by the 
parameters (including the records indicated by the parameter). To print only one record, the 
FROM and TO record keys should be the same. 
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In the OCL load sequence, you indicate which file is to be copied or printed. For files being copied, you must also indicate 
whether the file is being copied from one disk to another or from one location to another on the same disk. 

REORG-NO is assumed if you omit the REORG parameter. When OUTPUT-BOTH is used for indexed files, REORG-YES 
is required. 

WORK-NO is assumed if you omit the WORK parameter. 

If halt UC3CCS occurs, indicating that there is not enough core available to execute the job, consider the following: 


1. If you have OUTPUT-BOTH, change to OUTPUT-DISK. 


2. If you have REORG-YES, change to REORG-NO. 


3. 


If running on a DPF system, use a larger partition if possible. 



PARAMETER DESCRIPTIONS 

FROM and TO Parameters (COPYPACK) 

The COPYPACK statement is used to copy the con¬ 
tents of one disk to another. It has two parameters: 
FROM and TO. They tell the program the locations 
of the two disks on the disk unit. 

The FROM parameter (FROM-code) indicates the 
location of the disk you are copying. The TO para¬ 
meter (TO-code) indicates the location of the disk 
that is to contain the copy. The FROM and TO 
codes must be for the same type disk drive. You 
cannot copy a 5444 pack from or to a 5445 pack. 

Codes for the possible locations are as follows: 


from the fixed disk to the removable disk, the program 
prints another message telling the operator to remount 
the disk you are copying. The program repeats this 
procedure until all information has been transferred. 

Until the contents of the disk is completely copied 
on the new disk, three addressing portions of the 
new disk are changed to prevent accidental usage 
of a partially filled disk. Therefore, if the copying 
process is stopped before it is completed, the pack 
is unusable. You can restart the copying process 
by reloading the Disk Copy/Dump program, or 
you can resotre the disk by reinitializing. 

After a successful copy, the copy program prints 
a message: 


Code Meaning 

R1 Removable disk on 5444 drive one 

FI Fixed disk on 5444 drive one 

R2 Removable disk on 5444 drive two 

F2 Fixed disk on 5444 drive two 

D1 Removable disk on 5445 drive one 

D2 Removable disk on 5445 drive two 

Copying Entire Disk 


COPYPACK IS COMPLETE 

Note: If you copy a disk containing an active 
checkpoint, that checkpoint will exist on both 
the FROM and TO disks. When one of the two 
active checkpoints is utilized to restart the check- 
pointed program, care must be taken to ensure that 
the job is not restarted a second time. To ensure 
that this will not occur, it is recommended that you 
perform I PL and load Restart ($$RSTR) from the 
pack containing the second active checkpoint. If 
you then select the controlled cancel option when 
the Htfnn halt occurs (nn is the last requested check¬ 
point number), the checkpoint will be activated. 


When copying a disk, the Disk Copy/Dump program 
transfers the contents of the disk to another disk. 

The content of the two disks will be the same, except 
for the disk names and alternate track information 
which may be different. 

The disk you are copying can contain libraries or data 
files or both. The disk that is to contain the copy 
must not contain libraries, temporary data files, or 
permanent data files. 

The program can copy the contents of one removable 
disk to another using one disk drive. The drive 
however, must be drive one when using the 5444 
disk. (The system pack and the pack from which 
the Disk Copy/Dump program is loaded must be 
FI.) 

To do this the program needs 20 tracks on the fixed 
disk on drive one (5444 disk). It fills this space with 
information from the disk you are copying. Then it 
prints a message telling the operator to mount the 
other removable disk (the one to contain the copy) 
on drive one. After transferring the information 


OUTPUT Parameter (COPYFILE) 

The OUTPUT parameter is used when copying and 
printing data files. It indicates whether you want 
the program to copy, print, or copy and print a 
file. The OUTPTX parameter can be used to dis¬ 
play printed output in hexadecimal values. 

The parameter OUTPUT-DISK means to copy the 
file; OUTPUT-PRINT means to print the file; and 
OUTPUT-BOTH means to copy and print the file. 

The output file must be a new file unless the file 
you are copying over is a temporary file, in which 
case, the following rules apply: 

1. If R ECOR DS were used to create the tem¬ 
porary file, then the COPYO file card must 
specify RECORDS and LOCATION. 
RECORDS must be equal to the number 
used to create the original file. 
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2. If TRACKS were used to create the 

temporary file/then the COPYO file card 
must specify TRACKS and LOCATION. 
TRACKS must be equal to the number 
used to create the original file. 

Copying Files 

The Disk Copy/Dump program can copy a file from 
one disk to another or from one area to another on 
the same disk. 

The Disk/Copy Dump program cannot be used 
to copy a single volume file to a multivolume 
file or one volume of a multivolume file to a 
single volume file. 

The OCL load sequence for the Disk Copy/Dump 
program indicates (1) the name and location of the 
file being copied, and (2) the name and location of 
the copy being created. (See OCL Considerations 
in this section.) 

The program can copy a file from one removable 
disk to another using one disk drive. The drive, 
however, must be drive one. (See description of 
the WORK parameter for more information.) 

(The system pack and the pack from which the 
Disk Copy/Dump program is loaded must be FI.) 

In copying a file, the program can omit records. 
(See the description of the DELETE parameter 
for more information.) 

Printing Files 

The program can print all or part of a data file. 

To print only part, the program needs a SELECT 
control statement.. (See the description of the 
SELECT control statement parameters in this 
section.) If you do not use a SELECT statement, 
the entire file is printed. 

If you use SELECT or REORG, records from in¬ 
dexed files are printed in the order their keys 
appear in the index portion of the file; otherwise, 
they are printed as they appear in the file. For 
each record, the program prints the record key 
followed by the contents of the record. 

Records from sequential and direct files are print¬ 
ed in the order they appear in the file. For each 
record, the program prints the relative record 
number followed by the contents of the record. 


The program uses as many lines as it needs to print 
the contents of a record. Appendix A lists the 
hexadecimal numbers for characters in the standard 
character set. 

The following is an example of the way the program 
prints hexadecimal numbers using OUTPTX: 

ABCDE GHIJ 12345 

CCCCCBCCCDF F F F F4444444 
1 23456789 1 1 23450000000 

The hexadecimal number B6 represents a character 
that has no print symbol. 

After printing the last record, the printer triple 
spaces and prints the following message: 

(number) RECORDS PRINTED 


DELETE Parameter (COPYFILE) 

In copying a data file, the Disk Copy/Dump program 
can omit records of one type. The DELETE para¬ 
meter identifies the type of record. Use of the 
DELETE parameter is optional. If you do not use 
it, no records are deleted. 

The form of the parameter is DELETE-'position, 
character'-. Position is the position of the character 
in the records. Character is the character, except 
for apostrophes, blanks, or commas, that identifies 
the record. For example, with the parameter 
DELETE-'100,R', all records with an R in position 
100 are deleted. By specifying the hexadecimal 
code for the character, any character (including 
apostrophes, blanks, commas, and packed data) 
can be used to identify the records to be deleted. 

For example, with the parameter DELETE-'100, 
X40', all records with a blank (hexadecimal 40) 
in position 200 are deleted. 

Deleted records are always printed. If you are 
both copying and printing a data file, deleted 
records are printed with the other records that 
are printed. The deleted records are preceded 
by the word DELETE. 

The OMIT keyword can be used instead of 
DELETE. The deleted records are not printed 
if OMIT is used. 
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REORG (Reorganize) Parameter (COPYFILE) 

In copying an indexed file, the program can 
reorganize the file, such that the records in the 
data portion are in the same order as their keys in 
the file index. The REORG parameter tells the 
program whether or not to reorganize the file. 

REORG-YES means to reorganize. REORG-NO 
means not to reorganize. REORG-NO is assumed 
if you omit the parameter. 

If you tell the program to reorganize the file, the 
reorganization applies to the copy of the file 
rather than the original file. The original file is 
not affected. 

Reorganization (REORG-YES) is required when 
you are both copying and printing an indexed 
file (OUTPUT-BOTH). 

WORK Parameter (COPYFILE) 

The WORK parameter applies to copying a data 
file from (1) removable disk to another using 
the same disk drive (WORK-YES), or (2) one 
area to another on a removable disk on drive one 
(WORK-NO). It tells the program whether or not 
to use a work area on the fixed disk on drive one. 

The parameter WORK-YES means to use a work 
area. WORK-NO means not to use a work area. 
WORK-NO is assumed if you omit the WORK 
parameter. 

Work Area 

If you have only one disk drive, a common use of 
the Disk Copy/Dump program might be to copy 
a file from one removable disk to another. To do 
this, the program must use a work area on the 
fixed disk. 

If you are copying on 5445 drive one, the work 
area will be on R1. R1 must contain a minimum 
of 198 contiguous unused tracks. It is recommend¬ 
ed, however, that R1 contain no files or libraries 
as the number of pack changes on D1 will decrease 
with an increase in work area space. You cannot 
copy split cylinder files from D1 to D1 using 
WORK-YES. 


In copying the file, the program fills the work 
area with records from the file you are copying. 
Then it prints a message telling the operator to 
mount the other removable disk (the one to con¬ 
tain the copy) on drive one. After transferring 
the records from the work area to the removable 
disk, the program prints another message telling 
the operator to remount the disk containing the 
file you are copying. The program repeats this 
procedure until all records have been transferred. 

If you have two disk drives, you can still use the 
same drive to copy a file from one removable disk 
to another. The drive, however, must be drive one. 

You can copy a file from one area to another on the 
same disk. If you do, and the disk is a removable 
disk that you plan to mount on drive one, use the 
WORK-NO parameter. This keeps the program from 
using a work area on the fixed disk when it transfers 
the file from one area to the other. 

When using WORK-YES, the input and output files 
must have different labels, locations, or pack names. 
It is good practice to have different pack names on 
all packs in an installation. 

SELECT KEY and SELECT PKY Parameters 
(SELECT) 

The SELECT KEY and SELECT PKY parameters 
apply to printing part of an indexed file. The 
SELECT PKY parameter applies to printing part 
of the index file which contains packed keys. The 
parameters are FROM and TO. 

The FROM parameter (FROM-'key') gives the key 
of the first record to be printed. The TO para¬ 
meter (TO'key') gives the key of the last record to 
be printed. The record keys between those two in 
the file index identify the remaining records to be 
printed. If you want to print only one record, use 
the same record key in both the FROM and TO 
parameters. 

For example, the parameters FROM-'OOOIOO' and 
T0-'000199' mean that records identified by keys 
000100 through 000199 are to be printed. 

If the file index does not contain the key you 
indicate in a FROM parameter, the program uses 
the next higher key in the index. 
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You can omit the TO parameter. If you do, the 
program assumes that the last key in the index is 
the TO key. 

You can use fewer characters in the FROM or TO 
parameter than are contained in the actual keys; 
when keys are packed, however, you must use the 
same number of characters as contained in the 
actual keys. If you use fewer characters, the pro¬ 
gram ignores the remaining characters in the record 
key. The number of characters used in the FROM 
and TO parameters need not be the same. 

SELECT RECORD Parameters (SELECT) 

The SELECT RECORD parameters can apply to any 
file, but are normally used for sequential and direct 
files. These parameters use relative record numbers 
to identify the records to be printed. 

Relative record numbers identify a record's location 
with repsect to other records in the file. The rela¬ 
tive record number of the first record is 1, the 
number of the second record is 2, and so on. 

The SELECT RECORD parameters are FROM and 
TO. The FROM parameter (FROM-number) gives 
the relative record number of the first record to 
be printed. The TO parameter (TO-number) gives 
the number of the last record to be printed. Records 
between those two records in the file are also 
printed. 

For example, the parameters F ROM-1 and TO-30 
mean that the first thirty records (1-30) in the 
file will be printed. 

You can omit the TO parameter. If you do, the 
program assumes that the number of the last re¬ 
cord in the file is the TO number. If you want 
to print only one record, use the same number in 
the FROM and TO parameters. 

COPYING MULTIVOLUME FILES 

When copying multivolume files the first volume 
of the input file has to be online when the job is 
initiated. The output file must be a new file. If 
either condition is not satisfied, a halt occurs. 

Maintaining Proper Volume Sequence Numbers 

To maintain proper volume sequence numbers 
when copying a multivolume file, you must either 
copy all the volumes of the file in one run or copy 


only one volume for each run of $COPY. For 
example, if you copy a 3-volume file one volume 
at a time (volume 1 in the first run, volume 2 in 
the second run, and volume 3 in the third run), 
the volumes will retain their original sequence 
numbers in the output file. Or if you copy all the 
volumes (1,2, and 3) in the same run, the volume 
sequence numbers in the new file will be the same 
as in the orginal file. However, if you copy only 
volumes 2 and 3 in one run, their volume sequence 
numbers will be changed to 1 and 2 in the output 
file. 

$COPY will insure that all volumes of a multivolume 
file have the same date in the following manner. 

If only one volume of a multivolume file is copied, 
for each run of $COPY, the new file will assume 
the same data as the input file. If all volumes, or 
as in the example above, volume 2 and 3 of a 3- 
volume file are copied in a single run, the new file 
will assume the current system data. 

Maintaning Correct Relative Record Numbers 

To maintain correct relative record numbers when 
copying one volume of«a multivolume direct file, 
the size of the output volume must be the same as 
the size of the input volume. (If you want to in¬ 
crease the size of a file, you must copy the entire 
file.) If you copy the first volume of a 2-volume 
file and increase the number of records on that 
volume, you are also increasing relative record 
numbers of all records on the next volume. There¬ 
fore, to maintain the correct relative record num¬ 
bers, output and input volume extents must be 
equal if you are copying only one volume of a 
multivolume direct file. 

Direct File Attributes 

If you copy an entire multivolume direct file in 
one run, the output file will be given sequential 
attributes in the Volume Table of Contents 
(VTOC). However, this does not effect file pro¬ 
cessing. A file with either sequential or direct 
attributes can be accessed by a consecutive or 
random access method. If only one volume is 
copied, the direct attributes will be maintained. 

Copying Multivolume Indexed Files 

If you want to copy a multivolume file, REORG- 
YES must be given in the FILE statement. Since 
an unordered load to a multivolume indexed load 
is not permitted, a REORG-NO will cause a halt 
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if an out of sequence record is encountered. If 
you would prefer not to reorganize the file, it must 
be copied one volume at a time. When copying 
one volume at a time, the HI KEY on the output 
volume must be the same as the HI KEY on the 
input volume. Making the HIKEYs the same will 
ensure that both the input and output volumes 
are the same length and no records will be lost. 
When copying one volume of a multivolume file, 
either REORG-YES or REORG-NO may be 
specified. 


OCL CONSIDERATIONS 


The code you supply depends on the location of 
the disk containing the Disk Copy/Dump pro¬ 
gram. The codes are as follows: 

Code Meaning 

R1 Removable disk on drive one 

FI Fixed disk on drive one 

R2 Removable disk on drive two 

F2 Fixed disk on drive two 


The following OCL statements are needed to 
load the Disk Copy/Dump program, if you are 
using the program to copy an entire disk. 

// LOAD $COPY, code 
//RUN 
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If you are copying or printing files you must (1) 
describe the disk files being copied or printed and 
(2) describe the file being created. To do this, 
the following OCL statements are needed in the load 
sequence: 


// LOAD $COPY,code 

// FILE NAME-COPYIN,UNIT-code, PACK-diskname, LABEL-filename 
//FILE NAME-COPYO, UNIT-code, PACK-diskname, LABEL-filename, 


H ( TRACKS-number ) 
\ RECORDS-number / 

//RUN 


,RETAIN-code 


For further information on the 
FI LE statements, see Disk File 
Statement, File Processing 
Considerations in Part I of this 
manual. 


Statement 

Entry 

Considerations 

// LOAD 

— 

$COPY 

Name of Disk Copy/Dump 
program. 

code 

Location of disk con¬ 
taining Disk Copy/Dump 
program. Can be R1, R2, 

FI, F2. 

// FILE 

— 

NAME-COPYIN 

Name Disk Copy/Dump 
program uses to refer to 
file to be copied (input 
file). 

UNIT-code 

Location of disk containing 
file to be copied. Can be 
R1, R2, FI, F2, D1, D2. 

PACK-diskname 

Name of disk containing 
file to be copied. 

LABEL-filename 

Name by which file to be 
copied is identified on disk. 


Statement 

Entry Considerations 

//FILE 

NAME-COPYO Name Disk Copy/Dump 

program uses to refer to 
output file being created. 

UNIT-code Location of disk on which 

output file is to be created. 
Can be R1, R2, FI, F2, 

D1, D2. 

PACK-diskname Name of disk on which 

output file is to be identi¬ 
fied on disk. 

LABEL-filename Name by which output 

file is to be identified on 
disk. 

TRACKS-number Size of output file ex- 

RECORDS-number pressed either as number 

of records (RECORDS) 
or number of disk tracks 
(TRACKS). 

RETAI N-code Designation (temporary, 

permanent, or scratch) 
of output file. Can be 
T, P, or S. 

// RUN 
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EXAMPLES 

Figures 38 through 43 are three examples of the OCL 
statements and utility control statements needed to 
(t) copy an entire disk, (2) copy a file from one 
disk to another and (3) print part of a file. Each 
of the three examples has two figures. 
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Explanation: 

• The Disk Copy/Dump program is loaded from the fixed disk on 
drive one. 

Figure 38. OCL Load Sequence for Copying an Entire Disk 


Explanation: 

• The contents of the fixed disk on drive two (FROM-F2 in 
COPYPACK statement) is copied onto the removable disk on 
drive two (TO-R2). 

Figure 39. Utility Control Statements for Copying an Entire Disk 



Explanation: 

• Disk Copy/Dump program is loaded from fixed disk on drive one. 

• Input file (OCL sequence): 

1. Name that identifies file on disk is MASTER (LABEL-MASTER). 

2. Disk that contains the file is the fixed disk on drive one (UNIT-F1). 

Its name is A1 (PACK-A1). 

• Output file (OCL sequence): 

1, Name to be written on disk to identify the file is BACKUP (LABEL-BACKUP). 

2. Disk that is to contain the file is the removable disk on drive one (UNIT-R1). 

Its name is B2 (PACK-B2). 

3 0 The file is to be permanent (RETAIN-P). 

4. The length of the file is 50 tracks (TRACKS-50). 

Figure 40. OCL Load Sequence for Copying a File from One Disk to Another 
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Explanation: 

• The C0PYF1LE statement tells the program to create the output 
file using all the data from the input file. The output file is a 
copy of the input file. 

Figure 41. Utility Control Statements for Copying a File from One Disk to Another 
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Explanation: 

• Disk Copy/Dump program is loaded from the fixed disk on drive one. 


I Input file (OCL sequence): 

1. Name that identifies the file on disk is BACKUP (LABEL-BACKUP). 

2. Disk that contains the file is the removable disk on drive one (UNIT-R1). 
Its name is B2 (PACK-B2). 

Figure 42. OCL Load Sequence for Printing Part of a File 


1 HI HUM 


Explanation: 

• The file is being printed (COPYFI LE statement). 


• The file is an indexed file. The part being printed is identified by the record 
keys from ADAMS to BAKER in the index (SELECT statement). 


Figure 43. Utility Control Statements for Printing Part of a File 








DUMP/RESTORE PROGRAM - $DCOPY 


The Dump/Restore program ($DCOPY) is a utility program used with the IBM 
System/3 Model 10 Disk System control program. The $DCOPY program allows 
the user to copy or dump the entire contents of a disk onto tape. The tape then 
serves as a back-up copy in case something happens to the information on the disk. 
The disk can at any time be restored to its original contents by transferring informa¬ 
tion back from the tape. Important disks, such as those containing libraries and 
permanent data files, are normally the ones copied. The tape contains a copy of 
the data on all tracks, including those on cylinder 0, except for the alternate and 
CE tracks. 


CONTROL STATEMENT SUMMARY 


Uses 

Control Statements ( 1 ) 

(2) 

// COPYPACIv—TO-code ( [, PACK-name] 

Copy an entire 

disk to tape or 

| FROM-code i 

//end(JJ 

restore an entire 
disk from tape. 

Control statements are required in the order they are listed. 

(T) There can be 

only one COPYPACK statement in a program. 

f 3 ) END statement must appear only once in a program since it is a delimiter 
v indicating end-of-job. 


PARAMETER SUMMARY 

COPYPACK Statement 


Parameter 

Meaning 

FROM-code 

Location of disk to be copied. Possible codes are FI, R1, 

F2, R2, D1, D2. 

TO-code 

Location of disk to receive the copy. Possible codes are FI, 
R1, F2, R2, D1, D2. See Figure for relationship of FROM 
and TO locations. 

PACK-name 

Name of the disk pack being used. 
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PARAMETER DESCRIPTIONS 


FROM and TO Parameters (COPYPACK) 

The COPYPACK statement is used to copy informa¬ 
tion from disk to tape or from tape to disk. 

The FROM parameter (FROM-code) indicates the 
location of the disk being copied. The TO 
parameter (TO-code) indicates the location of disk 
to receive the copy. 

Codes for possible locations of FROM and TO 
parameters are: 


Code Location 

FI 5444, fixed disk on drive one 

R1 5444, removable disk on drive one 

F2 5444, fixed disk on drive two 

R2 5444, removable disk on drive two 

D1 5445, disk drive one 

D2 5445, disk drive two 

See Figure 44 for the relationship of FROM and TO 
locations. 


5444 Disk 

(FI, R1, F2, or R2) 


DUMP COPY 


and 

RESTORE COPY TO 



3410/3411 Tape 
(T1,T2, T3, or T4 as 
indicated on // FILE 
statement) 


5445 Disk 
(D1 or D2) 


DUMP COPY TO 


and 


<(^RESTORE COPY TO 


3410/3411 Tape 
(T1, T2, T3, or T4 as 
indicated on // FI LE 
statement) 


Notes: 

1. When copying disk to tape (dump), any pack may be specified as input including the IPL pack or program pack. 


2. When copying tape to disk (restore), the disk must not be the IPL pack, the program pack, or another pack con¬ 
taining libraries, temporary data files, or permanent data files. 


3. The disk receiving the copy at restore time must be the same type (5444 or 5445) and at least as large as the 
original disk. 


Figure 44. Relationship of Disk to Tape Drives when Using $DCOPY 
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PACK Parameter (COPYPACK) 


For 9-track tape: 

// FILE NAME-BACKUP,UN IT- 


The pack name specified will be checked against the 
actual name of the pack. A halt occurs if they are 
not the same. If the parameter is not used, no check¬ 
ing will occur. 


OCL CONSIDERATIONS 



i nnnnnn > 
l,REEL.j NL |l 

(T4) 

( filename on tape ) i mmddyy ) 

1,LABEL- ] 'character string'! ^ I.DATE- j ddmm yy | 1 

( code ) 

[,RETAIN-1 000 | ] [,BLKL-block length] 


The $DCOPY utility requires the following OCL 
statements: 

// LOAD, $DCOPY, code 


[,RECL-record length] [,RECFM-F] 


(LEAVE ) 
[,END- < REWIND > ] 
| UNLOAD ) 


( 800 ) 

[.DENSITY- | 1000 | ] 


// FI LE parameters 
// RUN 


FILE Statement When Copying From Tape to 
Disk (Restore) 


The code identifying the location of the $DCOPY 
program can be one of the following: 


Code Location 

R1 Removable disk on 5444 drive one 
FI Fixed disk on 5444 drive one 
R2 Removable disk on 5444 drive two 
F2 Fixed disk on 5444 drive two 


For 7-track tape: 


// FILE NAME-BACKUP,UNIT- 


T1 

T2 

T3 

T4 


,REEL- 


nnnnnn> 
NL [ 


( filename on tape 
[,LABEL- j Character string' 


[.DATE- j 


mmddyy 

ddmmyy 




FILE Statement When Copying From Disk to 
Tape (Dump) 


For 7-track tape: 

// FILE NAME-BACKUP,UNIT- 

filename on tape 



(nnnnnn i 

[, REEL - J NL [ ] 


( filename on tape i < mmddyy > 

[,LABEL- |'character string' [ ^ [^DATE- j (jqnrjmyy \ 


c code) 

[,RETAIN- | ooo P [,BLKL-block length] 


[,BLKL-block length] [,RECL-record length] 


(LEAVE } ( 200) 

[,RECFM-F] [,END-< REWIND > ] [,DENSITY-< 556 > ] 
j UNLOAD ) ( 800) 

,CONVERT-ON [,PARITY-ODD] [,TRANSLATE-OFF] 


Note: The DENSITY parameter must be the same 
number as specified for the dump. 


For 9-track tape: 


// FILE NAME-BACKUP,UNIT- 


T1 ) 

T2 ( 

T3 \ 

T4 ; 


( nnnnnn> 
,REEL-j. NL I 


[,RECL-record length] [.RECFM-F] 

(LEAVE ) ( 200) 

[.END- < REWIND > ] [.DENSITY-^ 556 > ] 

( unload ) (§00) 


< filename on tape i i 

[.LABEL- ) 'character string' ( ^ [.DATE-j 


mmddyy 

ddmmyy 


S 1 


[,BLKL-block length] [,RECL-record length] 


,CONVERT-ON[.PARITY-ODD] [,TRANSLATE-OFF] 


(LEAVE ) 

[.RECFM-F] [.END- < REWIND > ] 
( unload ) 
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Statement Entry 


Considerations 


// LOAD 


$DCOPY 


Name of Dump/Restore program. 


//FILE 


Location of disk containing Dump/Restore program. Can be R1, R2 r FI, F2. 


NAM E-filename 


Filename entry must be BACKUP. 


UNIT-code 


{ nnnnnn 1 
NL ) 


LABEL- 


filename on tape 
"character string' 


DATE-date 


The UNIT parameter is required. Code indicates tape unit. Allowable codes are: 
T1,T2, T3, T4 

The REEL parameter is optional when copying from disk to tape; it is required 
when copying from tape to disk. 

nnnnnn Volume is identified by coding a maximum of six characters, 
excluding commas, apostrophes, and blanks. 

NL Not labeled. The first record of an unlabeled tape must not be 

an 80-byte record beginning with VOLI. 

If REEL parameter is not specified, standard labels are assumed. 

The name of the tape file as it exists in the header label. 

Format can be mmddyy or ddmmyy. 


RETAIN-code 


Specifies number of days (000-998) a file should be retained. RETAIN 
parameter does not apply when copying from tape to disk. Default value 
when copying from disk to tape is 000. 


BLKL-block length 
RECL-record length 


Block length and record length, must be equal and one of the following values: 

Note: The tape record created is two bytes longer than specified since a two- 
byte logical record number is appended to the tape record. Defaults are 
underlined. 

Disk Length in Bytes Number of Tracks 


3072 

6144 

12288 

2560 

5120 

10240 


1/2 track 

1 track 

2 tracks 

1/2 track 

1 track 

2 tracks 


RECFM-code (record format) 


RECFM entry must be fixed length (F). 


END-position of tape after 
processing 


END entries can be LEAVE, REWIND, or UNLOAD. Default is UNLOAD. 


DENSITY- 


800 is the default when using 7-track tape; 1600 is the default value when using 
9-track tape. DENSITY parameter does not apply for the 9-track Restore opera¬ 
tion. If correct density is not specified (or defaulted) for the 7-track Restore 
operation, tape errors will occur. 
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Parameter Summary (Con't) 


Statement Entry 

Considerations 

CONVERT-ON 

For 7-track tape, CONVERT-ON must be specified; CONVERT-ON must 
be used for $DCOPY or data will be lost. Default is OFF. CONVERT-ON 
is not a valid parameter for 9-track tape. 

PARITY-ODD 

Should be specified if 7-track tape is used. PARITY-ODD must be used 
for $DCOPY or data will be lost. Default is ODD. 

TRANSLATE-OFF 

Do not use TRANSLATE-ON since TRANSLATE-ON and CONVERT- 
ON are mutually exclusive (cannot specify both as ON). TRANSLATE- 
ON specifies that a 64-character subset of EBCDIC is being used; characters 
outside the subset (such as X'00') are lost — translated without error 
indication to something that is not meaningful. Default is OFF. 

// RUN 

- 

For a detailed description of the OCL statements, see Part /, OCL Statements. 


Messages for DUMP/RESTORE 

Note: The following messages will be printed if the 1403 is the logging device and is not allocated to the other 
partition. 


Message 

Meaning 

Copypack is complete 

This message is printed when the 
specified pack has been dumped 
to tape or when the tape has 
been restored to disk. 

n tracks not restored at 

(cc/ss ) 

( CCC/hh/rr ) 

This message is printed when 
tracks have not been restored 

on the 5444 or 5445 disk, n = 

the number of tracks not res¬ 
tored. CC/SS is the disk 
address for a 5444 disk. 

CCC/hh/rr is the disk address 
for a 5445 disk. 

nn tape errors occurred 
pack is not completely 
restored. 

This message is printed when 
tape errors have occurred or the 
restored pack has missing data, 
nn = the number of tape errors. 

See previous messages for loca¬ 
tion of tracks not restored. 
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EXAMPLES 


Explanation: 


The parameters of the FILE statement vary depend¬ 
ing upon whether the copy is to or from the tape. 

Q FROM disk TO tape: 


— The Dump/Restore program is loaded from the 
fixed disk on drive one. 

— The file name is always BACKUP. 


Only required parameters are included in this ex¬ 
ample. See OCL Considerations for listing of 
possible parameters. 

OCL STATEMENTS 


1 4 8 12 16 20 24 28 
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— The copy will go to tape unit two. 

— Tape unit two is a 9-track drive. 


{Jl FROM tape TO disk: 

All possible parameters are included in this example. 


OCL STATEMENTS 

1 4 8 12 16 


20 


24 


28 


32 


36 


40 


44 


48 


52 


56 


60 


64 


1/ 
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Explanation: 

— The Dump/Restore program is loaded from the 
fixed disk on drive one. 

— The file name is always BACKUP. 

— Tape unit two contains the disk copy. 

— Tape unit two is a 7-track drive. 


— TAPE2 is the label of the tape volume. 

— KEEP5 is used in the header label. 

— The date is March 11, 1973. 

— Block and record lengths are 6144 and indicate 
that the disk device is a 5444. 

— CONVERT-ON indicates data conversion. 

— END, PARITY, and TRANSLATE parameters 
given are the same as the default values. 
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The following control statements show the use of 
all possible parameters. 


1 2 3 4 5 6 7 8 9 10 11 12 13 14 IS 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 3K 39 40 41 42 4 3 44 45 46 47 48 49 


l/l/l do 

p\ 
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T 

: K( 


-F 

, E 

9 K 

'X: 
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rOj 
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— The COPYPACK statement tells the program to 
copy an entire disk to tape. 

— The copy is from the fixed disk on drive one. 

— FIXED 1 is the name of the pack being used. The 
program will verify that the specified pack is 
mounted. 

Note: These utility control statements would be used 

with the OCL shown in example 1. 
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LIBRARY MAINTENANCE PROGRAM—$MAINT 


The Library Maintenance program has five functions: 


Function 

Meaning 

Allocate 

Create (reserve space for), delete, re-organize, and 
change the sizes of libraries. 

Copy 

Place entries in, and display the contents of, libraries. 

Delete 

Delete library entries. 

Modify 

Modify source library entries. 

Rename 

Change the names of library entries. 


The control statements you must supply depend on the function you are using. 

LIBRARY DESCRIPTION 

The source library is an area on disk for storing procedures and source statements. 
Procedures are groups of OCL statements used to load programs. The statements 
can be followed by input data for the programs. (Procedures for utility programs 
can, for example, contain utility control statements.) Source statements are sets 
of data, the most common of which are RPG II source programs and Disk Sort 
sequence specifications. 

The object library is an area on disk for storing object programs and routines. Object 
programs are programs and subroutines in such a form that they can be loaded for 
execution. (They are sometimes called executable object programs.) Routines are 
programs and subroutines that need to be link-edited into object programs before they 
can be loaded for execution. (They are sometimes called nonexecutable object 
programs.) 

Location of Libraries on Disk 

Libraries can be located anywhere on disk. However, the location of a source 
library with respect to an object library is always the same: 


User Area 


Source Library 


Object Library | User Area 


JL 


I 

Track 0 


Upper Boundary 


The boundaries of a source library are fixed. They can be changed only by the 
allocate function of the Library Maintenance program. The upper boundary of an 
object library, however, can be moved as additional space is needed when entries 
are placed in the library. This happens only if space is available following the library 
and if the entries being placed beyond the normal boundary are not permanent 
entries. 
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Organization of Library Entries 


Object Library 

Entries are stored in the object library serially; that is, a 20-sector program occupies 
20 consecutive sectors. Temporary entries follow all permanent entries in the object 
library. 

If necessary, the upper boundary is changed to allow more space for temporary 
entries. The upper boundary of the library is extended to the end of the pack or to 
the first temporary or permanent file, allowing the maximum amount of space for 
the temporary library entry. At the successful completion of the copy, the upper 
boundary is returned to its original position or to the end of the last temporary 
entry. If the copy was not completed successfully, the upper boundary may 
remain extended. When a permanent entry is placed in the library or the library is 
reorganized, all temporary entries are deleted and the upper boundary returns to 
its original location. Permanent entries cannot exceed the original upper boundary. 

Gaps can occur in the object library when an entry is deleted. The associated directory 
entries will point to these gaps. When the Library Maintenance program places a new 
entry in the library, it searches the directory for a gap that has the same number of 
sectors, or the fewest number of sectors over the number required by the new entry. 

If the entry is smaller than the gap, the last part of the gap will not be pointed to by a 
directory entry. Since this gap has no directory entry, it will not be used until the 
library is reorganized. 

If the number of unusable sectors becomes excessive, the library should be re¬ 
organized. In reorganizing entries, the Library Maintenance program deletes 
temporary entries and shifts entries so that gaps do not appear between them. This 
makes more sectors available for use. 

Source Library 

The source library differs from the object library in that entries within the source 
library need not be stored in consecutive sectors. An entry can be stored in many 
widely separated sectors with each sector pointing to the sector that contains the 
next part of the entry. When an entry is placed in the source library, it is placed in 
as many sectors as required regardless of where the sectors are located within the 
library. 

The boundary of the source library cannot be expanded; therefore, an entry must 
fit within the available library space. To provide as much space as possible with¬ 
in the prescribed limits of the source library, the system compresses entries. That 
is, all duplicate characters and blanks are removed from entries. Later, if the entries 
are printed or punched, the duplicate characters and blanks are re-inserted. 

When the size of the source library is changed or the source library is reorganized, 
all temporary entries are deleted. 

Library Directories 

The program creates a separate directory for each library. Every library entry has a 
corresponding entry in its library directory. The directory entry contains such infor¬ 
mation as the name and location of the library entry. The first character of a 
directory name must be an alphabetic character. Maximum length is six characters. 
The program also creates a system directory, which contains information about the 
size and available space in libraries and their directories. 



Organization of this Section 

The five functions of the Library Maintenance programs are described separately. 
Every description contains the following: 

1. List of specific uses. 

2. Control statement summary indicating the form of control statement needed 
for each use. 

3. Parameter descriptions explaining in detail, the contents and meanings of the 
parameters. 

4. Function descriptions explaining the details of each function. 

Following the function descriptions are: 

1. OCL considerations 

2. Examples 
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ALLOCATE FUNCTION 



ALLOCATE CONTROL STATEMENT SUMMARY 

//ALLOCATE TO-code,SOURCE- j" umber | .OBJECT- j ™ mber | ,SYSTEM- j | ,DIRSIZE-number,WORK-code 


Source 

Library 


Object 

Library 


Use^J 
Create 
Change Size 
Delete 
Reorganize 

Create 
Change Size 
Delete 
Reorganize 


Para me ter Needed 

TO-code,SOURCE-number,WORK~code( 

TO-code,SOURCE-number,WORK~code 

TO-code,SOURCE-0 

TO-code,SOURCE-R,WORK-code 


TO-cdde,OBJECT-number,SYSTEM- |j 
TO-code,OBJECT-number,WORK-code ( 3 ) 
TO-code, OBJECT-O 
TO-code,OBJECT-R,WORK-code © 


You can indicate a source library use, any object library use, or uses involving both libraries (for example, deleting the source 
library and changing the size of the object library). 

) 

If you are indicating uses for both libraries, use only one TO parameter. (The libraries must be on the same disk.) Also, use 
only one WORK parameter if both uses require a WORK parameter. 

The WORK parameter is needed only if the disk contains an object library that you are not deleting. 

The WORK parameter is not required if this is a compress in place. 









Library Maintenance Allocate Restrictions 

This program has restrictions and operating condi¬ 
tions that the user must be aware of when maintain¬ 
ing libraries. 

Allocation of Disk Space 

The Library Maintenance program allocates disk 
space for each of the following functions: 

— Allocate a library 
— Increase the size of a library 
— Reorganize a library 

— Dynamically extend an object library to copy 
temporary entries to the library 
— Sort a directory before it is printed 
— Modify a source library entry 

The space allocated by the program is the first con¬ 
tiguous space large enough for the function to be 
performed. The Library Maintenance program will 
use as much space as is available to the end of the 
pack or to the first temporary or permanent data 
file, removing all scratch files in this area. If within 
a single load of the program, there are functions 
performed which require more than four disk areas 
to be allocated, a halt will occur. The Library 
Maintenance program must be reloaded to continue. 

Removing Temporary Entries 

When a library is reorganized, its size is changed, or 
it is moved, all temporary entries in that library are 
deleted. This applies to both the source and object 
libraries. 


Library Restrictions 

The Allocate function cannot reference the libraries 
on the pack from which the Library Maintenance 
Program or the system was loaded. For example, if 
the system was loaded (IPL) from FI and the Library 
Maintenance Program was loaded from R1, the source 
or object libraries on FI and R1 cannot be referenced 
on an ALLOCATE statement. 


Moving the Object Library 

When allocating or reallocating the source library on 
a pack that contains an object library, the object 
library is reorganized and all temporary entries are 
deleted. 


ALLOCATE PARAMETER SUMMARY 

TO-code 

Location of disk you are using. 
Possible codes are R1, FI, R2, 
and F2. 

SOURCE-number (no 

Create a source library. Number 

source library on disk) 

indicates the number of tracks 
you want to assign. 

SOURCE-number (source 

Delete or change the size of the 

library already on disk) 

source library. Use depends on 
number: 

Number Use 

0 Del ete 

Any number Change size 

but zero 

SOURCE-R 

Reorganize the source library. 

OBJECT-number (no 

Create an object library. Number 

object library on disk) 

indicates the number of tracks 
you want to assign. 

OBJECT-number (object 

Delete or change the size of the 

library already on disk) 

object library. Use depends on 
number: 

Number Use 

0 Delete 

Any number Change size 

but zero 

OBJECT-R 

Reorganize the object library. 

DIRSIZE-number 

Number of tracks you want for 
the directory when creating, re¬ 
allocating, or reorganizing the 
object library. 

SYSTEM-NO 

Do not create a scheduler work 
area. This will be a program pack. 

SYSTEM-YES 

Create a scheduler work area. 

This will be a system pack. 

WORK-code 

Location of disk containing space 
the program can use as a work area. 
Possible codes are R1, FI, R2, or 

F2. 
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TO Parameter 

The TO parameter (TO-code) indicates the location 
of the disk that contains, or will contain, the library. 
If the program use involves both libraries, the 
libraries must be on the same disk. The TO para¬ 
meter cannot be the same unit from which the 
Library Maintenance program or system is loaded. 

Codes for the possible locations are as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 
drive two 

F2 

Fixed disk on drive 

two 

SOURCE and OBJECT Parameters 

These parameters identify library uses: 

Parameter 

Use 

SOURCE-number 

OBJECT-number 
(number is not zero) 

• If the disk contains 
no library, parameter 
means create a library. 
Number is the number 
of tracks you want to 
assign to the library. 


• If the disk contains a 
library, parameter 
means change the 
library size. Number 
is the number of tracks 
you want to assign to 
the library. 

SOURCE-O 

OBJECT-O 

Delete the library. 

SOURCE-R 

OBJECT-R 

Reorganize the library. 


DIRSIZE Parameter 

The Dl RSIZE parameter allows the user to specify 
the size of the object library directory. The number 
of tracks specified (1-9), overrides the SYSTEM 
parameter in determining directory size. Each track 
can contain 288 directory entries. One entry is 
needed for the directory, so the formula for the 
number of entries in a directory is (t x 288)-1, where 
t is the number of tracks. If the DIRSIZE parameter 
is omitted, the SYSTEM parameter determines the 
directory size. 


SYSTEM Parameter 

The SYSTEM parameter applies when creating, 
changing the size of and reorganizing object libraries. 
It tells the program whether you intend to include 
system programs in the library. If system programs 
are to be included, a scheduler work area must be 
assigned and the directory must be large enough for 
all those system programs necessary for program 
loading and running (minimum system), and those 
necessary for generating and maintaining a system. 

Space for the scheduler work area is assigned imme¬ 
diately preceding the object library. If the disk con¬ 
tains a source library, the work area is between the 
source and object libraries. For information about 
the size of the scheduler work area, see Scheduler 
Work Area Size. 

The following charts show the results of coding the 
SYSTEM parameter for different allocate users. 


Creating an Object Library 

Parameter Scheduler Work Area Directory Size * 

SYSTEM-YES Created Three Tracks 

SYSTEM-NO Not Created One Track 

not coded Not Created One Track 

*The directory size is overridden if the DIRSIZE 
parameter is coded. 
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Changing the Size of or Reorganizing an Object Library 
That Contains System Programs 

Parameter Scheduler Work Area Directory Size * 

SYSTEM-YES Retained Not Changed 

SYSTEM-NO Removed Not Changed 

not coded Retained Not Changed 

*The directory size is overridden if the DIRSIZE 
parameter is coded. 

Changing the Size of or Reorganizing an Object Library 
That Does Not Contain System Programs 

Parameter Scheduler Work Area Directory Size * 

SYSTEM-YES Created Not Changed 

SYSTEM-NO Not Created Not Changed 

not coded Not Created Not Changed 

*The directory size is overridden if the DIRSIZE 
parameter is coded. 

WORK Parameter 

The WORK parameter (WORK-code) indicates the 
location of the disk that contains a work area. 

Library entries are temporarily stored in the work 
area while the program moves and reorganizes 
libraries. 

Codes for the possible disk locations are as follows: 

Code Location 

R1 Removable disk on drive 1. 

FI Fixed disk on drive 1. 

R2 Removable disk on drive 2. 

F2 Fixed disk on drive 2. 

When the WORK parameter is coded on an ALLO¬ 
CATE statement, an additional allocation of disk 
space may result (s ee Allocation of Disk Space). 


Size of the Work Area 

The work area must be large enough to hold the 
permanent entries of the source library, object 
library, or both libraries depending on the program 
use. If you are combining uses, such as changing 
the sizes of both libraries,the work area must be 
large enough to hold the contents of both libraries. 


Use Con ten ts of Work Area 

Create a source Object library, 

library (disk con¬ 
tains an object 
library). 

Change source Source library and object 

library size (disk library, 

contains an ob¬ 
ject library). 

Change source Source library, 

library size (disk 
doesn't contain 
an object library). 

Reorganize Source library 

source library 

Change object Object library, if not 

library size. compress in place. 

(see compress in place.) 

Reorganize Object library, if not 

object library. compress in place. 

Location of Work Area on Disk 

The program uses the first available disk area large 
enough to hold the library, or libraries. 

Location of Disk Containing the Work Area 

The work area can be on either disk on either drive. 
However, it cannot be the same disk as the one you 
specified in the TO parameter. The only require¬ 
ment is that the disk must have an available area 
large enough for the work area. If your system has 
two disk drives, the program works faster if the disk 
containing the libraries is on a different drive than 
the disk containing the work area. 
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Using the Allocate Function 

Creating a Source Library (SOURCE-number) 


Source Library Size 

• Minimum: One track. 

• Maximum: Number of tracks in the available 
area. 

• Regardless of the number of tracks you specify, 
the first two sectors of the first track are assigned 
to the library directory. Additional sectors are 
used as needed for the directory. 


Placement of Source Library (Disk With an Object 
Library) 

• The source library must immediately precede the 
object library. A disk area large enough for the 
source library must follow the object library 
because the program moves the object library to 
make room for the source library (Figure 45). To 
do this, it needs a work area. (See WORK para¬ 
meter) The object library is reorganized and all 
temporary entries are deleted. 

• If you allocate a source library after deleting it, 
the program automatically moves the object 
library to make room for the source library. The 
starting location of the source library is the pre¬ 
vious starting location of the object library. 


Disk Space Before Creating Source Library 



Object Library 

Available Space 

Customer 1 


(30 tracks) 

(15 tracks 

Files \ 

0-7 


- OQ CO w 



-oo-bZ-► 



Tracks 


Disk Space After Creating Source Library 



Source 

Object Library 

Available 

Customer | 


Library 
(5 tracks) 

(30 tracks) 

Space 
(10 tracks) 

Files | 

0-7 

8-12 

-«-13-42-^ 

—43-52-*“ 



T racks 


Figure 45. Moving Object Library to Insert Source Library 


Placement of the Source Library (Disk Without an Object 
Library). The program assigns the source library to 
the first available disk area large enough for the 
library. 

If you allocate a source library after deleting it, the 
source library is assigned the same way. 

Changing the Size of a Source Library 

Any time the program changes the source library 
size, it reorganizes both the source and object 
libraries and deletes all temporary entries. (See 
Reorganizing a Source Library.) To do this, it needs 
a work area. {See WORK parameter.) 


Making the Source Library Larger 

• If the disk contains an object library space must 
be available immediately following the object 
library. The program moves the object library to 
make tracks available at the end of the source 
library (Figure 46). 

• If the disk does not contain an object library, 
space must be available immediately following 
the source library. 


Disk Before Tracks Are Added to Source Library 



Source 

Object 

Available 

Customer ] 


Library 
(10 tracks) 

Library 
(30 tracks) 

Space 
(15 tracks) 

Files l 

0-7 

8-17 

— 18-47 

48-62 



T racks 


Disk After Five Tracks Are Added to Source Library 



Source 

Object 

Available 

Customer \ 


Library 
(15 tracks) 

Library 
(30 tracks) 

Space 
(10 tracks) 

Files / 

0-7 

8-22 

— 23-52 

53-62 



T racks 


Figure 46. Increasing Source Library Size 
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Making the Source Library Smaller 

• If the disk contains an object library, the program 
moves the end location of the source library to 
make the library smaller. The object library is 
moved and space becomes available following the 
object library (Figure 47). 

• If the disk does not contain an object library, the 
program moves the end location of the source 
library to make the source library smaller. 


Disk Before Source-Library Size Was Decreased 



Source 
Library 
(15 tracks) 

Object 

Library 
(30 tracks) 

Customer ] 
Files > 

0-7 
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-23-52 -► 



T racks 


Disk After Five Tracks Were Taken From Source Library 



Source 

Object 

Available 

Customer \ 


Library 
(10 tracks) 

Library 
(30 tracks) 

Space 
(5 tracks) 

Files ( 

0-7 

8-17 

18-47 

48-52 



T racks 

Figure 47. Decreasing Source Library Size 


Deleting a Source Library (SOURCE-O) 

The program makes the disk area occupied by the 
source library available for other use (disk files) 
(Figure 48). 

Disk Before Source Library Deleted 


Reorganizing a Source Library (SOURCE-R) 

Reason for Reorganizing the Library. Areas from which 
source library entries are deleted are completely re¬ 
used for new entries. If an entry exceeds the space 
in such an area, the program puts as much of the 
entry as will fit in the area and continues the entry 
in the next available area. In this way, the program 
efficiently uses library space. This can, however, 
decrease the speed at which those entries can be 
read from the library. Therefore, if you frequently 
add and delete source library entries, you should 
reorganize your source library periodically. 

Reorganizing the Library. The program relocates entries 
so that no entry is started in one area and continued 
in another. All temporary entries are deleted. The 
program needs a work area. (See WORK parameter.) 

Creating an Object Library (OBJECT-number) 

Object Library Size 

• Minimum: Three tracks including the directory 
tracks. 

• Maximum: Number of tracks in available area. 

• Library Directory: The first three tracks in the 
library are reserved for the library directory if the 
library is to contain system programs; otherwise, 
only the first track is used. If the Dl RSIZE para¬ 
meter is entered, the directory size specified is 
used. 



Source 
Library 
(15 tracks) 

Object Library 
(30 tracks) 

Customer \ 

Files 

0-7 

- 8-22-► 

- 23-52-► 



Disk After Source Library Deleted 



Available 

Object Library 

Customer 1 


Space 
(15 tracks) 

(30 tracks) 

Files V 

0-7 

-*-8-22- 

^- 23-52 -► 



Figure 48. Deleting Source Library 
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• Scheduler Work Area: If the library is to contain 
system programs, the space available on the pack 
must be large enough to contain a work area for 
the Scheduler program (one of the system pro¬ 
grams). The work space is not included in the 
number you specify in the OBJECT parameter; 
the space is calculated and assigned by the Library 
Maintenance program. The amount of space 
needed depends on whether DPF (Dual Program¬ 
ming Feature) and/or the inquiry capability is gener¬ 
ated in the supervisor. For non-DPF systems, two 
tracks are needed; for DPF systems, four tracks are 
needed. The inquiry and checkpoint/restart features 
require additional tracks for a Roll-in/Roll-out 
area. The number of tracks needed depends on the 
main storage size of the system. 

Main Storage Size Roll-in/Roll-out Tracks 


12K 4 

16K 5 

24 K 6 

32K 8 

48 K 10 

64 K 13 


Placement of Object Library (Disk With a Source Library). 
Space for the object library must be available immed¬ 
iately following the source library. 


Placement of Object Library (Disk Without a Source 

Library). The program assigns the object library to 
the first available disk area that is large enough. 

Changing the Size of an Object Library (OBJECT-number) 

Making the Library Larger. The number of tracks you want 
to add must be available immediately following the 
object library. The program assigns the additional 
tracks to the library. (The starting location of the 
library remains unchanged.) 


Reorganizing the Library. Any time the program changes 
the library size it also reorganizes the library and 
deletes all temporary entries. (See Reorganizing an 
Object Library.) A work area is needed if other 
functions are being performed with the reorgani¬ 
zation. (See WORK parameter.) If not, a work 
area is not used. (See Compress in Place.) 

Deleting an Object Library (OBJECT-0) 

The program makes the disk area occupied by the 
object library (and the scheduler work area if this 
was a system pack) available for other use. 


Reorganizing an Object Library (OBJECT-R) 

Gaps can occur between object library entries when 
you add and delete entries. By reorganizing the 
library, these gaps are removed. When the library is 
reorganized, all temporary entries are deleted. A 
work area is needed if other functions are being 
performed with the reorganization. (See WORK 
parameter.) If not, a work area is not used. (See 
Compress in Place.) 

Compress in Place ^OBJECT - j n um b er |) 

If an object library is to be reorganized, or the 
size is to be changed and this is the only func¬ 
tion to be performed, the object library will be 
compressed in place. This means that the lib¬ 
rary will be reorganized with ail gaps removed 
and all temporary entries deleted without using 
a work area. The WORK parameter will be 
ignored if supplied. 

If, however, a source library function is to be 
performed or if the directory size (DIRSIZE 
parameter) or the pack type (SYSTEM parame¬ 
ter) is to be changed in conjunction with an 
object library function, a work area will be 
used. (See WORK parameter.) Compress in 
place allows the user with a single-spindle or 
half-capacity 5444 disk drive to reorganize 
the object library. 


Making the Library Smaller. The program moves the end 
location of the object library to decrease the library 
size. Tracks, therefore, become available following 
the library. 
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COPY FUNCTION 








COPY CONTROL STATEMENT SUMMARY: READER-TO-LIBRARY 


Add or Replace a Library Entry 

I 

// COPY FROM-READER,LIBRARY-< 

Library Entry 


S ' 
P 

1 ° 

R 


,NAME-names,TO-code,RETAIN- \ P 

r! 


// CEND <4 Must always follow the source or object entry being placed into 
the source or object library. 

/* or /& statements cannot be present in the entries being copied into the libraries. 


COPY CONTROL STATEMENT SUMMARY: FI LE-TO-LIBRARY 


Add or replace one or more library entries. 

13 °) 

// COPY FROM-DISK,FI LE-filename,RECL- j 96 j 


, TO-code,RETAIN- 




// COPY from-reader,library-o,retain-p,name-deckoi 


\ 


load module 


//CEND 



// COPY LIBRARY-S,NAME-DECK02 


source module 


//CEND 

//END 


Example 
of Data 
in Disk 
File 



Only the LIBRARY and NAME parameters are required. Other parameters are ignored. 

The // END card is optional as the FI LE-TO-LIBRARY copy will recognize the 
physical end of the data file and terminate the job. 





COPY CONTROL STATEMENT SUMMARY: LIBRARY-TO-LIBRARY 


© 


Copy One Library Entry (or Entries with the Same Name from AH Libraries) 

(S \ 

j p ) ( T ) 

// COPY FROM-code,LIBRARY-< O > ,NAME-name,TO-code,RETAIN-< P >,NEWNAME-name 

Ir \ Rj 

.all; 

Copy Library Entries that Have Names Beginning with Certain Characters 

S 1 

// COPY FROM-code,LIBRARY-<j O > ,NAME-characters.ALL,TO-code,RETAIN- | P | .NEWNAME-characters © 

. ALL/ 


Copy All Library Entries 


J p \ 

\ all; 


// COPY FROM-code^lBRARY-^ O } ,NAME-ALL,TO-code,RETAIN- { P 

R 


Copy Minimum System 

II COPY FROM-code,LI BRARY-0,NAME-SYSTEM,TO-code 


© 


NEWNAME parameter is needed in any of the following cases: 

1. If you want the copy to have a different name than the original entry. 
If you want to replace an entry on the TO disk with an entry from the 
FROM disk, but the entries have different names. 

If you want the names of the copies to begin with different characters 
than the names of the original entries, the same number of characters 
must be in the NEWNAME parameter as in the NAME parameter. 

If the FROM and TO packs are the same pack. 


2 . 


3. 


4. 


Note: Newname cannot be DIR, ALL, or SYSTEM. 
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COPY CONTROL STATEMENT SUMMARY: LIBRARY-TO-PRINTER-AND/OR-CARD 


Print and/or Punch One Library Entry (or Entries with the Same Name from AH Libraries) 


If COPY FROM-code,LIBRARY- 



NAME-name, TO- 


PUNCH ) 
PRINT > 
PRTPCH j 


Print and/or Punch Temporary and Permanent Library Entries that Have Names Beginning with 
Certain Characters 


II COPY FROM-code,LIBRARY-< 



[punch } 

,NAME-characters.ALL,TO- < PRINT > 
(PRTPCHj 


Print and/or Punch All Temporary and Permanent Library Entries of a Certain Type 


II COPY FROM-code.LIBRARY-/ ^ >,NAME-ALL,TO-< PRINT > 


{ PUNCH ] 
PRINT > 
PRTPCH j 


Print Directory Entries for Library Entries of a Certain Type 


II COPY FROM-code,LIBRARY-< Q V ,NAME-DIR,TO-PRINT 


Print Entries from All Directories Including System Directory 

H COPY FROM-code,LIBRARY-ALL,NAME-DIR f TO-PRINT 


Print System Directory Entries Only 


II COPY FROM-code,LIBRARY-SYSTEM,NAME-DIR f TO-PRINT 


Print Directory Entries, Omitting Selected Entries 


II COPY FROM-code,LIBRARY- 



,NAME“DIR,TO‘PRINT,OMIT- 


name 

characters. ALL 




COPY PARAMETERS 


FROM-READER 

Entry to be placed in library is to be read from system input device, which 
can be a keyboard or card reader. 

FROM-code 

Location of disk containing library entries being copied, printed, or punched. 

Possible location codes are: 


Code 

Meaning 


R1 

Removable disk on drive one 


FI 

Fixed disk on drive one 


R2 

Removable disk on drive two 


F2 

Fixed disk on drive two 

FROM-DISK 

The entry or entries to be placed into a library or libraries reside in a disk file. 

The disk file must be described by an OCL FILE statement. 

FILE-filename 

\ 80 i 

RECL- J 96 S 

For a file-to-library copy, this parameter is needed to identify the file on disk. 

The filename must match the filename on the OCL FILE statement. 

For a file-to-library copy, this parameter gives the size of the disk records. 

Only 80 or 96 column card image records (unblocked) are allowed. If this 
parameter is omitted, 96 is assumed. 

(?) 

LIBRARY-^ Q V 

Type of library entries involved in copy use. Possible codes are: 

\ R ) 

Code 

Meaning 


S 

Source statements (source library) 


P 

OCL procedures (source library) 


0 

Object programs (object library) 


R 

Routines (object library) 

LIBRARY-ALL 

All types of entries (S, P, 0, and R) from both libraries are involved in copy use. 

LIBRARY-SYSTEM 

Only system directory entries are being printed. 

( name ) 

NAME- < characters.ALL [• 

(all ) 

Specific library entries on the FROM pack, of the type indicated in LIBRARY 
parameter, involved in copy use. Possible information is: 


Information 

Meaning 


name 

Name of the library entry involved. 


characters.ALL 

Only those entries beginning with the indicated characters. 

The names of the copies and original entries will be the 
same unless you use a NEWNAME parameter (NEWNAME- 
characters). (You can use up to five characters.) 


ALL 

All entries. (The type indicated in LIBRARY parameter. 

To copy a system which you can 1 PL, specify LIBRARY- 
ALL and NAME-ALL.) 
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NAME-SYSTEM 


NAME-DIR 


NAME-$cc.ALL 


RETAIN- 


Only system programs that make up the minimum system are involved in the 
copy use. The minimum system is made up of system programs necessary to 
load and run programs. System programs necessary to generate and maintain 
the system are not included. 

Directory entries for all library entries of the type indicated in the LIBRARY 
parameter are involved in the copy use. If the LIBRARY parameter is 
LIBRARY-ALL, system directory entries are also printed. 

The IBM program with the name beginning with the indicated characters ($cc) 
is involved in the copy use. For example, $MA.ALL means the Library 
Maintenance program ($MAINT). 

Adding Entry to Library. RETAIN gives designation of the TO entry: 

Code Meaning 

T Temporary 

P or R Permanent 

Replacing Existing Library Entry. RETAIN gives designation of the TO entry and 
tells program whether to halt before replacing entry: 

Code Meaning 

T Temporary designation. Halt before replacing entry. 

P Permanent designation. Halt before replacing entry. 

R Permanent designation. Do not halt before replacing 

entry. 

Printing or Punching Entries. The RETAIN parameter is ignored. 


TO-code 


TO-PRINT 

TO-PUNCH 

TO-PRTPCH 

NEWNAME-name 


NEWNAME-characters 


OMIT-name 


Location of disk that is to contain the copies of the entries: 
Code Meaning 

R1 Removable disk on drive one 

FI Fixed disk on drive one 

R2 Removable disk on drive two 

F2 Fixed disk on drive two 


Entries are being printed. 

Entries are being punched. 

Entries are being printed and punched. 

Name you want used on the TO disk to identify the entries being put on that 
disk. If you omit this parameter, the program uses the NAME parameter in 
naming the entries. 

Beginning characters you want to use in names identifying entries being put 
on TO disk. You must use the same number of characters as in the NAME 
parameter (NAME-characters.ALL). If you omit this parameter, the program 
uses the NAME parameter in naming the entries. 

When printing directory entries, omit the entry specified by name. 


OMIT-characters.ALL 


When printing directory entries, omit all entries with these beginning 
characters. 
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Library Directories 


Source and Object Library Directories 

• The source and object libraries have separate 
library directories. Every library entry has a 
corresponding entry in its library directory. The 
directory entry contains such information as the 
name and location of the library entry (see 
Figures 49-51). 

• The Library Maintenance program makes entries 
in the directories when it puts entries in the 
libraries. 


System Directory 

• Every disk that contains libraries contains a 
system directory. The system directory contains 
information about the sizes of and available 
space in libraries and their directories (see 
Figures 49-51). 

• The Library Maintenance program creates and 
maintains the system directory. 

Naming Library Entries 

Characters to Use. Use any combination of System/3 
characters except blanks, commas, quotes, and 
periods. (Appendix A lists the characters.) The 
names of all IBM programs begin with a dollar sign 
($). Therefore, to avoid possible duplication, do not 
use a dollar sign as the first character in the names 
you use for your entries. The first character must be 
alphabetic. 

Length of Name. The name can be from one to six 
characters long. 

Restricted Names. Do not use the names ALL, DIR, and 
SYSTEM. They have special meanings in the NAME 
and NEWNAME parameters. 


Entries with the Same Name. For each of the two physical 
libraries, source and object, there are two types of 
entries. The source library has type P and type S 
entries. The object library has type O and type R 
entries. Entries of the same type cannot have the 
same name, but entries of different types may. For 
example, two procedures in a source library cannot 
have the same name, but a procedure and a set of 
source statements can. 


Retain Types 

Temporary Entries 

• Temporary entries are entries you do not intend 
to keep in your libraries. They are normally used 
only once or a few times over a short period. 

• In the object library, temporary entries are placed 
together following the permanent entries. Any 
time a permanent entry is added to the library, all 
temporary entries are deleted. Temporary entries 
are also deleted when you replace one permanent 
entry with another. 

• In the source library, temporary and permanent 
entries can be in any order. One entry is placed 
after another regardless of their designations. 
Temporary entries, therefore, are not automatically 
deleted every time you add a permanent entry. 
However, when the source library is reallocated or 
reorganized, only permanent entries will remain. 

• You can use temporary entries as often as you 
like until they are deleted. 

• A temporary entry cannot replace a permanent 
entry. 

Permanent Entries 

• Permanent entries are entries you intend to keep 
in your libraries. They are normally entries you 
use often or at regular intervals (once a week, 
once a month, and so on). 

• The program will not delete permanent entries 
unless you use the delete function of Library 
Maintenance to delete them, or the allocate 
function to delete the entire library. 
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Using the Copy Function 

Reader-to- Library 

Input. The program reads one library entry, it can be any 
one of the following types; 

1. Source statements 

2. Procedure 

3. Object program 

4. Routine 

The entry is read from the system input device, which 
is normally the primary hopper of the MFCU. The 
operator can, however, change the system input 
device by using the OCL READER statement. 

The header card on an object deck (H in column 1) 
contains the date the deck was punched. This date is 
in columns 58-63 and is in the format of the system 
date, either mmddyy or ddmmyy. 

Output 

• Blanks and duplicate characters are removed from 
source statements and procedures before they are 
put in the source library. The program does not 
check them for errors. 

• Object programs and routines are placed in the 
object library. 


Adding Entries 

• The program can add a new entry to a library. 

The name of the entry is taken from the NAME 
parameter. See Naming Library Entries for valid 
names. The RETAIN parameter specifies whether 
the entry will be temporary or permanent. If the 
RETAIN parameter is omitted, RETAIN-T is 
assumed, (see Retain Types) 

Replacing Existing Entries 

• The program can replace an existing library entry 
with the entry you are putting in the library. The 
RETAIN parameter specifies the new retain type. 
If the RETAIN parameter is omitted, RETAIN-T 
is assumed. A temporary entry cannot replace a 
permanent entry. 


• Before the new entry is added, the duplicate entry 
is deleted. Additional library space is not needed 
unless the new entry is larger than the old one. 

File-to-Library 


Input. The disk file can contain one or more library entires. 
The entries must be in the format put out by the 
library-to-card function or by the linkage editor. The 
// COPY statement at the beginning of each entry 
contains the name of the entry and the type of library 
(S,P,0,R). A // CEND statement must follow each 
entry in the file. 

The disk file must be a sequential 5444 file and be 
defined by a FI LE statement in the OCL for the 
Library Maintenance program. 

Output. The output from the file-to-library function is the 
same as for the reader-to-library function except that 
temporary entries are not allowed, 

Library-to-Library 

Input. The program can copy one or more library entries 
from one disk to another. The types of entries can 
be: 

1. Source statements 

2. Procedures 

3. Object programs 

4. Routines 

5. All the preceding types 

6. Minimum system 

The NAME and LIBRARY parameters specify which 
entries to copy. 


• The program can halt before replacing an existing 
entry. Whether it does depends on the RETAIN 
parameter you use. (see RETAIN parameter) 
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Output 

• The entries, regardless of their type, are copied 
from one disk to the other without change. How¬ 
ever, if all library entries are copied (LIBRARY- 
ALL, NAME-ALL), the object library is reorgan¬ 
ized and temporary entries become permanent 
entries in both the source and object libraries. 

• Entries can be copied and renamed on the same 
disk by using the NEWNAME parameter, (see 
NEWNAME parameter and Naming Library 
Entries) 

• If you are copying a minimum system or all of the 
types (LIBRARY-ALL, NAME-ALL), the object 
library on the disk you specify in the TO parame¬ 
ter must be empty. That is, it cannot contain any 
entries or deleted entries. When LIBRARY-ALL, 
NAME-ALL is specified and the FROM disk is a 
system pack, then the TO disk will be a system 
pack. 

• The RETAIN parameter specifies whether the 
entries will be temporary or permanent. If the 
RETAIN parameter is omitted, RETAIN-T is 
assumed. When the parameters LIBRARY-ALL 
and NAME-ALL or LIBRARY-0 and NAME- 
SYSTEM are used, RETAIN-P is assumed and 
RETAIN-T is invalid. 

Adding Entries 

• You can omit the NEWNAME parameter. If you 
do, the name used for the copy is taken from the 
NAME parameter. (The copy will have the same 
name as the original entry.) 

• If NAME-ALL is specified, the names by which 
the entries are identified on the FROM disk are 
also used on the TO disk to identify the entries. 

Replacing Existing Entries 

• The program can replace existing entries with the 
entries you are putting in the library. If the entry 
you are copying (the entry on the disk you identi¬ 
fy in the FROM parameter) has the same name as 
the entry you are replacing (the entry on the disk 
you identify in the TO parameter), you must omit 
the NEWNAME parameter because the NEWNAME 
parameter cannot be the same as the NAME para¬ 
meter. If the names are not the same, you must 
use the NEWNAME parameter to give the name of 
the entry being replaced. 


Library-to-Printer and/or Card 


Types of Entries that Can Be Printed or Punched 

• The program can print or punch one or more 
library entries. They can be any one of the 
following types: 

1. Source statements 

2. Procedures 

3. Object programs 

4. Routines 

5. All of the preceding types (limited to entries 
having the same name and entries beginning 
with the same characters) 

• The program can print (but not punch) the follow¬ 
ing types of directory entries: 

1. Source statements 

2. Procedures 

3. Object programs 

4. Routines 

5. System directory 

6. All of the preceding types 

The program will sort directory names before 
printing them only if there is available work space 
on the FROM pack. This causes an allocation of 
disk space. (See Allocation of Disk Space.) 


Printed or Punched Library Entries 

• Blanks and duplicate characters are reinserted 
into source statements and procedures to make 
them readable. 

• Object programs and routines are printed and 
punched as they exist in the library. 


• The program can halt before replacing an existing 

entry. Whether it does depends on the RETAIN Printout of Directory Entries 

parameter. (See RETAIN parameter.) _ _ 

• Source library directory (Figure 49) 

• A temporary entry cannot replace a permanent . 0bject |jb dj (Figure 50) 

entry. 

• System directory (Figure 51) 
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PRINTOUT 


SOURCE DIRECTORY FROM XX VOL. ID XXXXXX MM/DD/YY 


ADDRESS 



TYPE NAME 

FIRST@ LAST@ 

ATTRI 

#SECTORS 

X XXXXXX 

xxx-xx xxx-xx 

X 

XXXX 


Explanation: 

Heading Meaning 

TYPE S = source statements 

P = procedure 

NAME Name of library entry (up to six characters) 

ADDRESS Addresses of first and last sectors that contain the library entry. 

(FIRST and LAST) Addresses are expressed by track and sector numbers. 

EXAMPLE: 008-03 means track 8, sector 3. 

ATTRI T = temporary 

P = permanent 

■^SECTORS Total number of sectors used for the library entry. 


Figure 49. Source Library Directory Printout 


PRINTOUT 


OBJECT DIRECTORY FROM XX VOL. ID XXXXX MM/DD/YY 




DSK 

CYL / 

TXT- 

LINK 

RLD 

ENTRY 

CORE 



TOT 

TYPE 

NAME 

ADD 

SEC 

CAT 

ADDR 

DISP 

PNT 

SEC 

ATTR 

LEVEL 

SEC 

X X 

XXXXXX 

TTT/SS 

CC/SS 

XXX 

XXXX 

XX 

XXXX 

XXX 

XXXX 

XXX 

XXXX 


EXPLANATION: 

Heading 

TYPE 


NAME 
DSK ADD 

CYL/SEC 

TXT-CAT 


Meaning 

The fist character printed indicates the attributes of the entry as follows: 

P = permanent 
T = temporary 

The second character printed indicates the type of module the entry is. Its 
meaning is as follows: 

O = Object program 
R = routine 


Name of library entry (up to six characters) 

Address where library entry begins on disk. EXAMPLE: 015/10 means track 15, sector 10 
(in decimal). T = track, S = sector. 

Address where library entry begins on disk (in hexadecimal). C = cylinder, S = sector. 

For object programs, this number indicates the number of sectors used for the text portion of 
the library entry. Object programs consist of two parts: text and RLD. Text is the program; 
RLD is information used in loading the program for execution. 

For routines, this number is the category of the routine. This number is used by the Overlay 
Linkage Editor for determining overlays. 


Figure 50 (Part 1 of 2). Object Library Directory Printout 
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PRINTOUT (Continued) 



Heading 

Meaning 


LINK ADDR 

Object programs only. Assigned core hexadecimal address of this library entry. 

RLD DISP 

Object programs only. It indicates the hexadecimal position in which RLD information begins in 
the last text sector. If the last text sector contains no RLD information, the RLD displacement 
is 0, indicating the information starts in the next sector. 

ENTRY PNT 

Object programs only. Main storage address hexadecimal where program execution begins before 
relocations. 

CORE SEC 

Core size 

given in sectors, required to run the program. 

ATTR 

Byte 1: 



Bit 0=1 

Permanent Entry 


0 

Temporary Entry 


Bit 1=1 

Inquiry. This program requires that the Inquiry key be pressed to start processing. 


Bit 2=1 

Inquiry Invoking. This program runs in program level 1 and can be rolled out to 
allow an Inquiry program to run. 


Bit 3=1 

Dedicated. In a DPF system, this program must run with the other program level 
inactive. 


Bit 4=1 

Source Required. This program requires the allocation of the $WORK and $SOURCE 
files. $SOURCE must be filled either from the system input device or a source library. 


Bit 5=1 

Deferred Mount. This program accepts mounting of packs during its execution. 


Bit 6=1 

PTF Applied. A program temporary fix (PTF) has been applied to this program. 


Bit 7=1 

Overlay Object Program 


Byte 2: 



Bit 0=1 

System Input Dedication. The system input device must be dedicated to this program. 

The device is released at end of job. 


Bit 1=1 

Checkpoint/Restart Program 


Bit 2=1 

Direct Source Read. This program can have a // COMPILE statement and a no source 
required attribute (byte 1, bit 4=0). The program will access the source itself. 


Bit 3=1 

Macro Processor Allowed. This program can be preceded by the macro processor. 

If the source required attribute is present and a // SWITCH 1XXXXXXX statement 
was processed, the $SOURCE file is opened as input instead of output. 


Bit 4 

Reserved 


Bit 5=1 

Program Common. This program requires that a new load address be calculated at 
load time to place it in main storage beyond its own program common region. 


Bit 6 

Reserved 


Bit 7 

Reserved 

LEVEL 

Release level of system programs. For user programs this can be assigned by the Overlay 

Linkage Editor. 

TOT SEC 

Total number of disk sectors occupied by the library entry. 


Figure 50. Object Library Directory Printout (Part 2 of 2) 
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SYSTEM DIRECTORY FROM xx VOL. ID xxxxxx mm/dd/yy 


SOURCE LIBRARY SECTION 


Source Directory Location TTT-SS 

Next Available Library Sector TTT-SS 

End of Library TTT-SS 

Number of Directory Sectors XXX 

Number of Permanent Library Sectors XXX 

Number of Active Library Sectors XXX 

Number of Available Library Sectors XXX 

Allocated Size of Library YYY 

OBJECT LIBRARY SECTION 

Object Directory Location TTT-SS 

Allocated Size of Directory YYY 

Start of Library TTT-SS 

Allocated End of Library TTT-SS 

Extended End of Library TTT-SS 

Number of Available Permanent Directory Entries XXX 

Number of Available Temporary Directory Entries XXX 

First Temporary Directory Entry TTT-SS-DDD 

Next Available Temporary Directory Entry TTT-SS-DDD 

Next Available Library Sector for Permanents TTT-SS 

Next Available Library Sector for Temporaries TTT-SS 

Number of Available Library Sectors for Permanents ( 2 ) XXX 

Number of Available Library Sectors for Temporaries XXX 

Number of Active Library Sectors XXX 

Number of Active Object Permanent Library Sectors XXX 

Number of Active Routine Permanent Library Sectors XXX 

Allocated Size of Library YYY 

Roll-in/Roll-out Location TTT-SS 

Roll-in/Roll-out Size YYY 

Scheduler Work Area Location TTT-SS 

Scheduler Work Area Size YYY 

Start of Libraries TTT-SS 

End of Libraries TTT-SS 




TTT-SS-DDD means track, sector, and displacement. Displacement is the number of characters from 
the beginning of the sector. XXX means number of sectors. YYY means number of tracks. 

Number of Available Library Sectors for Permanents reflects the space available from the last per¬ 
manent library entry to the allocated end of the library. Gaps and temporary library entries are not 
reflected in this figure. The actual number of sectors available for permanent entries may be calcu¬ 
lated by subtracting Number of Active Object Permanent Library Sectors from the total number of 
sectors in the library. If the result is much larger than Number of Available Library Sectors for Per¬ 
manents, the library should be reorganized using the ALLOCATE function to remove gaps and tem¬ 
porary object library entries. 


Figure 51. System Directory Printout 




DELETE FUNCTION 
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DELETE PARAMETERS 

FROM 'W 

Location of disk that contains library entries you are deleting. Possible codes are: 

v F2 / 

Code 

Meaning 


R1 

Removable disk on drive one 


FI 

Fixed disk on drive one 


R2 

Removable disk on drive two 


F2 

Fixed disk on drive two 

\ 

LIBRARY-< 0 > 

r 

V ALL 7 

Type of entries being deleted. Possible codes are: 

Code Meaning 


S 

Source statements {source library) 


P 

Procedures (source library) 


0 

Object programs (object library) 


R 

Routines (object library) 


ALL 

All types of entries (S, P, 0, and R) are being deleted. 

/ name \ 

NAME-< characters.ALL > 

(all ) 

Particular entries, of type indicated in LIBRARY parameter, being deleted. These 
entries are further identified by the RETAIN parameter. Possible codes are: 


Code 

Meaning 


name 

Name of the library entry, or entries, being deleted. 


character.ALL 

Entries that have names beginning with the indicated 
characters. You can use up to five characters. 

EXAMPLE: NAME-INV.ALL refers to the entries 
having names that begin with INV. 


ALL 

All entries (of the type indicated in LIBRARY parameter). 
NAME-ALL cannot be used with LIBRARY-ALL. 

RETAIN- j l 

Designation of entries being deleted: 

) 

Code 

Meaning 


T 

Temporary 


P 

Permanent 
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MODIFY FUNCTION 



MODIFY RESTRICTIONS 


• Sequence numbers are a physical part of the source record and must be placed where they will not 
conflict with other data in the record. In a procedure they should be placed near the end of the 
record beyond the OCL and utility control statements' keywords and parameters. The sequence 
numbers should be placed in source statements where they will not overlay data. For example, 
data could be destroyed if sequence numbers were placed in RPGII source statements that con¬ 
tained compile-time tables. 

• At least three control statements must be entered to modify the source library. A // MODIFY 
statement is needed to describe the library entry. A // REMOVE, // REPLACE, or // INSERT 
statement describes the type of modification. A // CEND statement indicates the end of the con¬ 
trol statements. 

• The sequence numbers specified by the FROM-seqno, TO-seqno, and AFTER-seqno parameters on 
the // REMOVE, // REPLACE, and // INSERT statements must be valid numbers and exist in the 
source library entry. There are no default values for these parameters. The number of digits entered 
must be the same as the number of positions specified by the SEQFLD parameter. 

• All statements in a source library entry must have ascending sequence numbers in the positions 
specified by the SEQFLD parameter. 

• Multiple operations (REMOVE, REPLACE, INSERT) may be performed within the same MOD¬ 
IFY run if they are done in an ascending sequential order. That is, the FROM sequence number in 
a REMOVE or REPLACE statement must be greater than the last sequence number in the preced¬ 
ing statement. The AFTER sequence number of an INSERT statement must be equal to or greater 
than the last sequence number of the preceding statement. Consecutive INSERT statements must 
not have the same sequence number. 

• When modification is complete, the directory entry is written back with a permanent attribute. 

• The control statements following the // MODIFY statement are read from the system input device, 
which can be the keyboard or a card reader. Since the REMOVE control statement is valid for both 
the $DELET utility and $MAINT utility, care should be used when modifying a $DELET procedure. 
The program will attempt to determine if the REMOVE statement is data or a control statement. 

If a determination cannot be made, the program will halt and wait for further instructions. 
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MODIFY CONTROL STATEMENT SUMMARY 




YES ( YES ) 

WORK-code,RESER- < NO \ .LIST- ’ Yc;> ' 

ONLY \ 




Initiate Modification 

// MODIFY NAME-name,FROM-code,LI BRARY- 

SEQFLD-xxyy,INCR-number x 7 

Control Statements Following // MODIFY 

Delete all statements between and including the FROM and TO sequence numbers. 

// REMOVE FROM-seqno, TO-seqno 

Replace all statements between and including the FROM and TO sequence numbers with the statements supplied. 
// REPLACE FROM-seqno, TO-seqno 


1 - n statements to replace those removed 

Insert the supplied statements after the statement indicated by the AFTER parameter. 
// INSERT AFTER-seqno 
1 - n statements to be inserted 




MODIFY PARAMETERS 


NAME-name 


FROM-code 


Current name of the entry you are modifying. This is the name that identifies the entry in 
the library directory. 

Location of the disk that contains the entry you are modifying. Possible codes are: 


Meaning 


Removable disk on drive one 


Fixed disk on drive one 


Removable disk on drive two 


Fixed disk on drive two 


LIBRARY- 


Type of library entry you are modifying. Possible codes are: 


Meaning 

Source statements (source library) 


Procedures (source library) 


WORK-code 


Location of the disk containing space the program can use as a work area. Possible codes 


Meaning 


Removable disk on drive one 


Fixed disk on drive one 


Removable disk on drive two 


\ YES 
RESER- / N£ 

) ONLY 


F2 Fixed disk on drive two 

Specifies whether reserialization should be done when the entry is placed back in the source 
library. Possible information is: 


Information 


Meaning 


Reserialization is done. 

Reserialization is not done. NO is assumed if the RESER parameter 
is omitted. 


r-{^} 


ONLY Reserialize only; no other maintenance is done. When this is coded, 

no REMOVE, REPLACE, or INSERT statements can be entered. 

A // CEND statement is not needed. 

Specifies whether the source library entry should be listed when the MODIFY run is complete. 
NO is assumed if the LIST parameter is omitted. 


SEQFLD-xxyy 


INCR-number 


The starting and ending positions of the field that contains the sequence number. The sequence 
number can be up to eight digits long. The starting position is entered first (xx) and then the 
ending position (yy). If this parameter is not entered, 9296 is assumed. 

Increment value for sequence field if reserialization (RESER-YES or RESER-ONLY) is 
specified. The value can be up to five digits. If this parameter is not entered, a value of 10 is 
assumed. 
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REMOVE, REPLACE, INSERT PARAMETERS 


FROM-seqno 

The sequence number of the first 
statement to be used in the 
operation. 

TO-seqno 

The sequence number of the last 
statement to be used in the 
operation. 

AFTER-seqno 

The sequence number of the state¬ 
ment after which the new statements 

are to be added. 


RENAME FUNCTION 


RENAME USE 


Change the name of a library entry. 

Change the name of library entries that have names 
beginning with certain characters. 


! RENAME CONTROL STATEMENT SUMMARY 


( s i 

| // RENAME FROM-code,LIBRARY-<j ^ j> ,NAME-name,NEWNAME-name 


// RENAME FROM-code,LIBRARY-< P > ,NAME-characters.ALL,NEWN AM E-characters 

h) 


RENAME RESTRICTIONS 


• System modules should not be renamed on the 
active system pack (the pack the system was 
loaded from during I PL). 


• Library Maintenance modules should not be 
renamed on the active program pack. 













RENAME PARAMETERS 

FROM-code 

Location of disk that contains the entry 
you are renaming. Possible codes are: 


Code 

Meaning 


R1 

Removable disk on drive one 


FI 

Fixed disk on drive one 


R2 

Removable disk on drive two 

f P | 

LIBRARY- < Q \ 

VR ) 

F2 Fixed disk on drive two 

Type of library entry you are renaming. 
Possible codes are: 


Code 

Meaning 


S 

Source statements (source 
library) 


P 

Procedures (source library) 


0 

Object programs (object library) 


R 

Routines (object library) 

NAME-name 

Current name of the entry you are re¬ 
naming. This is the name that identifies 
the entry in the library directory. 

NAM E-characters. ALL Only those entries beginning with 


the indicated characters. (You can § 


use up 

to five characters.) 

NEWNAME-name 

New name you want to give the entry. 
Follow these rules to construct the name: 


1 . 

You can use any System/3 charac¬ 
ters except blanks, commas, quotes, 
and periods. (Appendix A lists the 
characters.) However, the names 
of all IBM programs begin with a 
dollar sign ($). Therefore, to avoid 
possible duplication, do not use a 
dollar sign as the first character in 
the names you use for your entries. 
The first character must be alpha¬ 
betic. 


2. 

You can use up to six characters, 
but you cannot use the names ALL, 
DIR and SYSTEM. They have 
special meanings in the NAME 
parameter. 

NEWN AM E-characters Beginning characters you want to use in 


names identifying the copies. (You can 
use up to five characters. 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the Library Maintenance utility program. 

// LOAD $MAINT,code 

// RUN 

The code you supply depends on the location of 
the disk containing the Library Maintenance pro¬ 
gram. The codes are as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 

drive two 

F2 

Fixed disk on drive 

two 


EXAMPLES 

Figures 52-67 illustrate the functions of the Library 
Maintenance utility program. Figure 52 is an exam¬ 
ple of the OCL needed to load the utility program. 
The other figures are examples of the control state¬ 
ment necessary to carry out the specified function. 



Explanation: 

• Library Maintenance program is loaded from the fixed disk on 
drive one 

Figure 52. OCL Load Sequence for Library Maintenance 
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Explanation: 

• Libraries are being created on the removable disk on drive one (T0-R1 in ALLOCATE statement). 

• Source library space is 12 tracks (SOURCE-12). 

• Object library space is 45 tracks (OBJECT-45). The object library will contain system 
programs (SYSTEM-YES). Thus, the disk area will also include space for the Scheduler work area. 

• Directory will be three tracks. 

Figure 53. Allocate Example. Creating Both Source and Object Libraries on a Disk 



Explanation: 

• Source library is located on the removable disk on drive one 
(TO-R1 in ALLOCATE statement). 

• Size of the source library is being changed to 1 5 tracks 
(SOURCE-15). 

• Any time the program changes the size of a library, it re¬ 
organizes the library. To do this, it needs a work area. This 
area is on the fixed disk on drive one (WORK-F1). 

Figure 54. Allocate Example: Changing the Size of a Source 
Library 
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Explanation: 

• Object library is located on the removable disk on drive one 
(TO-R1 in ALLOCATE statement). 

• OBJECT-O parameter tells the program to delete the object 
library. If a Scheduler work area precedes the object library, 
it is also deleted. 

Figure 55. Allocate Example: Deleting the Object Library from 
a Disk 



Explanation: 


• System programs are in the object library on the fixed disk on drive one 
(LIBRARY-0 and FROM-F1 in COPY statement). 

• The NAME parameter (NAME-SYSTEM) tells the program to copy the 
system programs. 

• The disk that is to contain the copy is the removable disk on drive one 
(TO-R1). 

Figure 56. Copy Example: Copying Minimum System from One Disk to Another 
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Explanation: 

• All library directories and the system directory on the removable disk on drive one 
are printed (COPY statement): 

| 

1. FROM identifies the disk containing the directories. 

2. LI BRARY indicates which directories are to be printed. 

3. NAME and TO indicate that the program is to be printing directories. 

4. All entries beginning with a $ are not printed. 

Figure 57. Copy Example: Printing Library Directories 
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Explanation: 

• LIBRARY-0, NAME-ACCT, and FROM-R1 in the COPY statement tell the program 
to read the object program named ACCT from the removable disk on drive one. 

• TO-F1 tells the program to copy the object program to the fixed disk on drive one. 
There is no NEWNAME parameter in the COPY statement. Therefore, the name the 
program will have on the fixed disk is ACCT (NAME-ACCT). Since the old version 
of the program already exists on the fixed disk under that name, the old version is 
replaced. 

• The Library Maintenance program normally halts before replacing a library entry. 
The RETAIN-R parameter, however, tells the program to omit that halt. 

Figure 58. Copy Example: Copying Object Program to FI 


m 


Explanation: 

• The program deletes a set of source statements (LIBRARY-S in 
DELETE statement) named PAYROL (NAME-PAYROL) from 
the removable disk on drive one (FROM-R'I) that has a temporary 
attribute. 

Figure 59. Delete Example: Deleting an Entry from a Library 
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Explanation: 

• The OCL for a File-to-Library copy must contain a FILE statement 
for the disk file. 

• The filename on the // COPY statement (FI LE-BSCAFILE) 
matches the filename on the OCL FI LE statement (NAME- 
BSCAFILE). 

• The // COPY statement does not contain an RECL parameter, 
so a record length of 96 is assumed. 

• All source and object decks in the disk file must have a 

// COPY statement as the first card image. These // statements 
(including the // END statement) are printed with XX replacing 
the // to indicate they were read from disk rather than from 
the system input device. 

• All source and object decks in the disk file must have a 
// COPY statement as the first card image and a // CEND 
statement as the last card to indicate the end of the copy 
for each deck. These // statements (including the // END 
statement) are printed with XX replacing the // to indicate 
they were read from disk rather than from the system input 
device. 

Note: The // CEND statement is not printed. 

• The // END statement read from the file (printed XX END), 
causes the next statement to be read from the system input 
device. All END statement must still be read from the 
system input device to indicate the end of the Library 
Maintenance control statements. 

Note: The // END statement in the file is optional as the 
system will recognize the physical end of the data file 
and terminate the copy. 

Figure 60. Copy Example: Disk File to Library 
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Explanation: 

• The entries being deleted are on the removable disk on drive one 
(FROM-R1 in DELETE statement). 

• The program deletes all entries from both source and object 
libraries (LIBRARY-ALL) that have names beginning with the 
characters INV (NAME-1 NV.ALL), with temporary attributes. 

Figure 61. Delete Example: Deleting AH Entries with Names that Begin with Certain Characters 
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Explanation: 

• The entries being deleted are on the removable disk on drive one 
(FROM-R1 in DELETE statement). 

• All temporary procedures are being deleted from the source 
library (LIBRARY-P,NAME-ALL). 

Figure 62. Delete Example: Deleting All Library Entries of One Type 
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Explanation: 

• The source module named INPUT1 on disk drive R1 is being modified. 

• The work space will be on R1. 

• The sequence numbers are in positions 1-5 of the statements. 

• Sequence numbers 00124 - 00156 are being deleted from the module. 

• The module is reserialized with increments of one. 

• The module is not listed. 

Figure 63. Modify Example: Removing Source Statements from a Module 
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Explanation: 


• The procedure named POCOI on disk drive R2 is being modified. 

• The work space will be on R1. 

• The sequence numbers are in default positons 92-96. 

• Statements with sequence numbers 00101-00102 are being replaced. 

• The module is not reserialized. 

• The module is listed. 

Figure 64. Modify Example: Replacing Statements in a Procedure 



• The removable disk on drive one contains the entry being renamed (FROM-R1 
in RENAME statement). 

• The entry is a set of source statements in the source library (LIBRARY-S). 

Its name is ACCT (NAME-ACCTh 

• The entry name is being changed to ACCT1 (NEWNAME-ACCT1). 

Figure 65. Rename Example: Renaming a Set of Source Statements in a Source Library 



• The source module COST on disk drive FI is being modified. 

• The work space is on FI. 

• The sequence numbers are in positions 80-84 of the statements. 

• A statement is being inserted after statement number 00070. 

• The module is reserialized with the default increment value of 10. 

• The module is listed. 

Figure 66. Modify Example: Inserting a Statement in a Source Module 
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Reload System (IPL) from R1 
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Reload System (IPL) from FI 


Explanation: 

1. The system and $MAINT are both loaded from FI. 

2. The libraries on R1 are deallocated (if present). 

3. New library space is allocated on R1. 

4. The libraries are copied from FI to R1. The object library is reorganized as it is copied. 
Temporary entries become permanent when copied (see Disk-to-Disk Considerations, Output). 

5. The system and $MAINT are now loaded from R1. 

6. The libraries on FI are deallocated. 

7. New library space is allocated on F1. 

8. The libraries are copied back to FI. The pack on R1 could be used as a back-up pack. It 
contains the same libraries as FI. 

Figure 67. Reorganizing the System Pack 
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IBM SYSTEM/3 5445 DATA INTERCHANGE UTILITY PROGRAM-$VTOC 


All IBM 2316 disk packs initialized on System/3 5445 Disk Drive by $1NIT have a System/360- 
System/370 formatted volume table of contents (VTOC). The System/360-System/370 
VTOC is not used by System/3. When it is necessary to exchange data between System/3 and 
System/360-System/370 on a 2316 disk pack, the IBM System/3 5445 Data Interchange 
Utility can be used (see Appendix C for an alternate method). The utility must be run going 
to and returning from System/360-System/370. 

When the utility program is run against a 2316 disk pack, the contents of the System/3 
VTOC are mapped to the System/360-System/370 VTOC. If data is to be returned to the 
System/3 via the utility without reinitialization, then restrictions on the use of the pack on 
System/360-System/370 must be observed. Any deviations from these restrictions can 
result in the format of the pack being altered beyond the capacity of the utility to return 
the pack to normal System/3 format. This can result in errors in the utility run returning 
the pack or unrecoverable errors on the pack while processing it on System/3. 

Following is a list of the methods of processing data files on the interchange pack by OS 
or DOS: 


Functions (sequential processing only) 

Disposition 

Type 

Open 

Reading with OS using BSAM or QSAM 

OLD 

FBS 

INPUT 

Output with OS using BSAM or QSAM 

OLD 

FB or FBS 

OUTPUT 

Reading with DOS using SAM-GET 

— 

— 

INPUT 

Update in place with OS using BSAM or 
QSAM 

OLD 

FBS 

UPDATE 

Update in place with DOS using SAM- 
GET/PUT 


UPDATE 

INPUT 


CAUTION: 

Only the above disposition and open types may be used. 

The update-in-place function can be used on a data set written on System/3 filled with 
dummy records. Since duplicate file names are not allowed on System/360-System/370, the 
System/3 file names will be qualified with the file date. An example would be PAYROLL. 
D711026. PAYROLL would be the file name on System/3 and the file was created on 
October 26, 1971. 

Files to be processed by QSAM must have a logical record length that is an even submultiple 
of 256. 

No files may be allocated or deleted on System/360 or System/370 if the pack is to 
be read on System/3 without reinitializing. 
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Any System/3 P or T file on the pack is mapped into the System/360-System/370 VTOC. 
Multivolume files are not supported and their interchange results in a System/360- 
System/370 entry that appears like a single volume file. Split cylinder files will have a 
System/360-System/370 format one but it is not usable due to basic differences in split 
file philosophy between the systems. If the System/3 file type is either sequential or 
indexed but not split, then a System/360-System/370 end-of-file mark is written in the 
file area at the end of data (256 bytes must be available). When the utility is run to 
return the pack to System/3, the end of file marks are removed and the System/360- 
System/370 VTOC entries are deleted. 

The utility must always be run just before going to System/360-System/370 and just 
after returning to System/3. Any deviation from this procedure can result in loss of 
data on the pack. 

The attributes of all System/360-System/370 VTOC entries assigned by the utility are 


as follows: 


Name of file 

name. DYYMMDD 

Creation date 

00000 

Expiration date 

— 99365 (date protected) 

Volume sequence number 

0001 

Record/block format 

FIXED BLOCK STANDARD (FBS) 

Organization 

— sequential (regardless of S/3 type) 

System Code 

"IBM DSM/3" 

Block length 

- 256 bytes 

Logical record length 

— same as S/3 length 

Extent type 

— single 


CONTROL STATEMENT SUMMARY 


System/3 to System/360-System/370 Conversion 

,PACK-name 




// NEWVTOC UNIT- 
// END 

System/360Sy$tem/370 to System/3 Conversion 


// UPDATE UNIT 
// END 


{£} 


r PACK-name 


PARAMETER SUMMARY 

PACK-name Name of the disk. 

UNIT-code Location of the disk. Possible codes 

are D1 and D2. 
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PARAMETER DESCRIPTIONS 


PACK Parameter 

The PACK parameter (PACK-name) tells the pro¬ 
gram the name of the pack being transferred. The 
name you supply in this parameter is the one written 
on the disk by the Disk Initialization program. 

The 5445 Data Interchange program compares the 
name in the PACK parameter with the name on the 
disk to ensure they match. In this way, the program 
ensures that it is using the right disk. 



Explanation: 

• 5445 Data Interchange Utility is loaded from the fixed disk 
on drive one. 


UNIT Parameter 

The UNIT parameter (UNIT-code) tells the program 
the location of the pack being transferred. Codes for 
the possible locations are as follows: 


Code Meaning 

D1 Removable disk on 

5445 drive one 

D2 Removable disk on 

5445 drive two 


OCL CONSIDERATIONS 

The following OCL statements are needed to load 
the 5445 Data Interchange Utility program: 

// LOAD $VTOC, code 
// RUN 

The code you supply depends on the location of the 
disk containing the utility program. The codes are 


as follows: 


Code 

Meaning 

R1 

Removable disk on 

drive one 

FI 

Fixed disk on drive 

one 

R2 

Removable disk on 
drive tyvo 

F2 

Fixed disk on drive 

two 
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APPENDIX A. IBM SYSTEM/3 STANDARD CHARACTER SET 



Appendix A. IBM System/3 Standard Character Set 
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APPENDIX B. CONVERSION 


RECORDS TO TRACKS CONVERSION 


Determining the Number of Sequential or Direct File Tracks 

The following two steps should be followed to determine the number of tracks in a 
sequential or direct file. (Round results to the next higher whole number.) 

1. number of records x record length = number of characters 

2. number of characters (from step 1) 

® = number of tracks 

. 


Determining the Number of Indexed File Tracks 

The following two steps should be used to determine the number of data tracks in an 
indexed file: 


t. number of records x record length = number of characters 

2. number of characters (from step 1) 

® = number of data tracks (round to the next 

higher whole number) 

The following four steps should then be followed to determine the number of index 
tracks in an indexed file: 


1 . 

2 . 


key field length + (3 for 5444 or 4 for 5445) = index entry length 


number of characters in a sector 
index entry length (from step 1) 



number of entries per sector 


3. number of records 

number of entries per sector (from step 2) 


number of sectors 


4. 


number of sectors (from step 3) 

- /'JN 

number of sectors per track ^ 


number of index tracks (round to the next 
higher whole number) 


0 


6144 for the 5444 
5120 for the 5445 


© 


256 (For 


the 5445, a sector is referred to as a fixed record.) 


© 


24 for the 5444 
20 for the 5445 
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If an indexed 5445 file has more than 15 index tracks (from step 4 above), the file 
will have a disk master index in addition to the regular index. The following two 
steps should be followed to determine the number of tracks needed for the master 
index: 


1. number of index tracks (greater than 15) 
number of entries per sector (from step 2) 


number of fixed records 


2. number of fixed records (from step 1) 
20 


number of disk master index tracks 
(round results to the next higher 
whole number) 


The total number of tracks in a 5445 indexed file can be determined by adding the 
number of data tracks, the number of regular index tracks, and the number of disk 
master index tracks. 


CYLINDER/TRACK TO TRACK NUMBER CONVERSION 

To convert cylinder/track to track number, multiply cylinder number by the number 
of tracks on each cylinder and add track. 

EXAMPLE: 5/3 = cylinder/track 

5 X 20*+3 = 103 
103 = track number 

TRACK NUMBER TO CYLINDER/TRACK CONVERSION 

To convert track number to cylinder/track, divide track number by the number of 
tracks on a cylinder. The quotient is the cylinder and the remainder is track. 

EXAMPLE: 103 = track number 

103 20* = 5 (remainder 3) 

5/3 is the cylinder/track 


20 = number of tracks on a cylinder 
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APPENDIX C. SYSTEM/360-SYSTEM/370 DISK FILE COMPATIBILITY 


This appendix is intended for the user who intends to exchange data between System/3 
and System/360-System/370 without using the IBM System/3 5445 Data Interchange 
Utility Program. The access method limitations listed in the utility program section of 
this manual should be followed. 

Disk files created on the 5445 can be read and updated using System/360-System/370. 
Disk files can also be created using System/360-System/370 and subsequently read or 
updated with a System/3 Model 10 Disk System. 

The Volume label and volume table of contents (VTOC) identify the information con¬ 
tained on the disk pack. The volume label identifies the volume and points to the 
System/360-System/370 VTOC. The System/360-System/370 VTOC contains one label 
record which describes the complete pack as one System/360-System/370 file. The 
System/3 VTOC resides in a fixed location within this System/360-System/370 file and 
can be examined by the System/360-System/370 program. 

See IBM System/3 Disk Systems System Control Program Logic Manual SY21 -0502, 
for a description of the System/3 VTOC and volume label. 


System/3 to System/360-System/370 

The System/3 Disk Initialization Program writes a volume label in the System/360- 
System/370 format on every disk pack. The System/3 disk format consists of 
256-byte physical records. This record length may be altered for System/360- 
System/370 VTOC records. 

Any of the access methods previously listed may be used by System/3 when creat¬ 
ing a file to be used by System/360-System/370. The logical records in a particular 
System/3 file can be accessed by System/360-System/370 by means of a user pro¬ 
gram using the Sequential Access Method if the user program: 

• Locates the file label in the System/3 VTOC for the desired file. 

• Uses the start of data information and record length information from the 
System/3 VTOC to perform the accessing and logical deblocking. 

• Uses the end-of-file information from the System/3 VTOC. 


System/360-System/370 to System/3 

Volumes created on System/360-System/370 can be processed on System/3 if 
System/360-System/370 provides a System/3 VTOC entry and writes 256-byte 
physical records. A System/3 user program or utility can then read and unblock 
the file according to the information in the System/3 VTOC. 

CAUTION 

If the System/3 VTOC provided by System/360-System/370 is not exactly 
the same as the System/3 format, unexpected results (destroyed data files 
or unrelated halts) may occur. 
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* parameter for the LOAD statement (OCL) 17 
$ALT {see Alternate Track Assignment program) 
$BUILD (see Alternate Track Rebuild program) 
$COPY (see Disk Copy/Dump program) 
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ASCII parameter 

FI LE statement 48 
VOL statement 90 
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automatic file allocation 73 


BLKL parameter, FILE statement 46 
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Allocation of Disk Work Space 151 
control statement summary 150 
DlRSIZE parameter 152 
function 151 
OBJECT parameter 152 
parameter summary 151 
restrictions 151 
SOURCE parameter 152 
SYSTEM parameter 152 
TO parameter 152 
WOR K parameter 153 
allocation limit 151 

Alternate Track Assignment program 105 
ALT statement (see ALT statement) 
cancel prior assignment 108 
conditional assignment 107 
examples 109 
messages 110 
OCL considerations 109 
unconditional assignment 108 
Alternate Track Rebuild program 111 
examples 113 
OCL considerations 113 
REBUILD statement (see REBUILD statement) 
substitute data 112 
ALT statement ($ALT) 

ASSIGN parameter 108 
control statement summary 106 
PAC K parameter 107 
parameter summary 106 
UNASSIGN parameter 108 
UNIT parameter 107 
VERIFY parameter 107 


CALL statement (OCL) 51 
cancel prior alternate track assignment 108 
CAP parameter for the UIN statement 101 
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example 109 
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conversion 

cylinder — tracks 190 
records — tracks 189 
track number — cylinder number 190 
convert seven track tape 48 
COPY statement ($MAINT) 

control statement summary 158-160 

File-to-library 164 

FROM parameter 161 

function 157 

LIBRARY parameter 161 

library-to-card 165 
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DENSITY parameter 47 
END parameter 47 
example 40-42 

file processing considerations 42 
format 33 
function 33 
HI KEY parameter 39, 67 
LABEL parameter 
disk 36 
tape 45 

LOCATION parameter 37, 67 
NAME parameter 
disk 33 
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PUNCH statement 30 
READER statement 29 
RUN statement 20 
SWITCH statement 21 
format parameter for the IMAGE statement 
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indicating the number of lines per page the printer will print 27 

indicator-settings parameter for the SWITCH statement 21 

initializing disks 97 

initializing tapes 89 

input device, changing (see READER statement) 
input/output devices in a DPF environment 74 
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REMOVE statement ($DELET) 
control statement summary 122 
DATA parameter 124 
DATE parameter 124 
LABEL parameter 123 
PACK parameter 123 
parameter summary 123 
UNIT parameter 123 
REMOVE statement ($MAINT) 
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